docs/hover-feature-description

README.md

@@ -33,7 +33,7 @@ explains items, coverage and artifact types.
 | Feature                                                             | What it gives you                                                |
 |---------------------------------------------------------------------|------------------------------------------------------------------|
 | [Syntax highlighting](doc/user-guide/README.md#syntax-highlighting) | Item IDs, section keywords and coverage tags in their own colors |
-| [Hover documentation](doc/user-guide/README.md#hover-documentation) | Title and description of the item an ID refers to                |
+| [Hover documentation](doc/user-guide/README.md#hover-documentation) | What the item an ID refers to says, section by section           |
 | [Go to definition](doc/user-guide/README.md#go-to-definition)       | From a tag to the item, from an item to everything covering it   |
 | [Find references](doc/user-guide/README.md#find-references)         | Every coverage tag in the workspace that covers an item          |
 | [Symbol search](doc/user-guide/README.md#symbol-search)             | Items through the editor's workspace symbol search               |

doc/demo/README.md

@@ -35,10 +35,15 @@ are colored.
 ### 2. Hover
 
 In `src/CoffeeMaker.java`, hover over the target of the first coverage tag,
-which is `dsn~brew-cycle~1`.
+which is the implementation of `dsn~brew-cycle~1`.
 
 > **Expected:** title and description of the design item appear as a tooltip.
 
+Now hover over `dsn~heat-water~2` two tags further down.
+
+> **Expected:** below the description the tooltip also shows the item's
+**Comment**, the section the specification carries for it.
+
 ### 3. Go to definition
 
 a) In the same tag, invoke *Go to Definition* on the target

doc/spec/features.md

@@ -15,9 +15,9 @@ The language server lists all coverage tags in the workspace that cover a given
 Needs: req
 
 ## Hover Documentation
-feat~hover-documentation~1
+feat~hover-documentation~2
 
-The language server shows a hover tooltip over a coverage tag. The tooltip contains the specification item's title and description.
+The language server shows a hover tooltip over a coverage tag. The tooltip describes the specification item the tag refers to.
 
 Needs: req
 

doc/spec/requirements.md

@@ -36,7 +36,7 @@ req~hover-specification-item~1
 When the user hovers over a coverage tag, the server returns a Markdown response describing the specification item.
 
 Covers:
-* feat~hover-documentation~1
+* feat~hover-documentation~2
 
 Needs: impl, utest
 

doc/user-guide/README.md

@@ -9,7 +9,7 @@ The [demo walkthrough](../demo/README.md) does exactly that.
 | Feature                                     | Description                                       | 
 |---------------------------------------------|---------------------------------------------------|
 | [Syntax highlighting](#syntax-highlighting) | IDs, keywords and tags get their own colors       |
-| [Hover documentation](#hover-documentation) | Title and description of the referenced item      |
+| [Hover documentation](#hover-documentation) | What the referenced item says, section by section |
 | [Go to definition](#go-to-definition)       | Between a tag and the item, in both directions    |
 | [Find references](#find-references)         | Every tag covering an item                        |
 | [Symbol search](#symbol-search)             | Find items by ID or title                         |
@@ -39,9 +39,19 @@ own name (`[impl~login~2->...]`) and needed coverage (`[dsn->req~login~1>>impl,u
 
 ## Hover documentation
 
-Pointing at a specification item ID shows the title and description of the item
-it refers to, wherever the ID appears: in a coverage tag, in a `Covers:` list or
-on the declaration itself.
+Pointing at a specification item ID shows what the item it refers to says,
+wherever the ID appears: in a coverage tag, in a `Covers:` list or on the
+declaration itself.
+
+Title and description come first. Below them the tooltip repeats the sections
+the item carries, each behind its keyword: `Rationale:`, `Comment:`, `Depends:`
+and `Tags:`, and `Status:` where it is not `approved`. A section the item does
+not carry is left out.
+
+`Needs:` and `Covers:` are missing on purpose. Both say where the item sits in
+the trace, which the [code lens](#coverage-code-lens) and
+[go to definition](#go-to-definition) answer against the current trace instead
+of repeating what the item declares.
 
 ![Hover documentation](images/hover.png)
 

intellij-plugin/src/main/resources/META-INF/plugin.xml

@@ -7,7 +7,7 @@
         (OFT) language server into the IDE via the built-in LSP client. The server understands
         OFT specification items and coverage tags and provides:
         <ul>
-            <li><b>Hover documentation</b>: title and description of the referenced specification item</li>
+            <li><b>Hover documentation</b>: shows what the referenced specification item says</li>
             <li><b>Go to definition</b>: from a coverage tag to the specification item and from an item to all its covering tags</li>
             <li><b>Find references</b>: all coverage tags in the workspace that cover a specification item</li>
             <li><b>Trace diagnostics</b>: uncovered specification items, links to items that do not exist and duplicate definitions, reported for every file in the project and listed under <i>Project Errors</i></li>
@@ -21,6 +21,9 @@
             <li><b>Code completion</b>: specification item IDs in <code>Covers:</code> sections and coverage tag targets</li>
             <li><b>Tag skeletons</b>: pressing Ctrl+Space in a comment offers a skeleton such as
                 <code>[impl-&gt;...]</code> for every artifact type the workspace needs, including project specific ones</li>
+            <li><b>Trace decisions</b>: an architecture decision record written as
+                <a href="https://github.com/adr/madr">MADR</a> can carry a specification item ID
+                and is then traced like a requirement</li>
             <li><b>Ignore file</b>: glob patterns in a <code>.oftignore</code> file in the project root
                 exclude files from all OFT features, on top of the build output and hidden paths
                 that are excluded by default</li>

vscode-extension/README.md

@@ -2,7 +2,7 @@
 
 Integrates the [OpenFastTrace](https://github.com/itsallcode/openfasttrace) (OFT) language server into VS Code via the built-in Language Server Protocol client. The server understands OFT specification items and coverage tags and provides:
 
-* **Hover documentation**: title and description of the referenced specification item
+* **Hover documentation**: shows what the referenced specification item says
 * **Go to definition**: from a coverage tag to the specification item and from an item to all its covering tags
 * **Find references**: all coverage tags in the workspace that cover a specification item
 * **Trace diagnostics**: uncovered specification items, links to items that do not exist and duplicate definitions, reported for every file in the Problems view
@@ -15,6 +15,7 @@ Integrates the [OpenFastTrace](https://github.com/itsallcode/openfasttrace) (OFT
 * **Syntax highlighting**: specification item definitions, section keywords and coverage tags via semantic tokens
 * **Code completion**: specification item IDs in `Covers:` sections and coverage tag targets
 * **Tag skeletons**: invoking completion manually in a comment offers a skeleton such as `[impl->...]` for every artifact type the workspace needs, including project specific ones
+* **Trace decisions**: an architecture decision record written as [MADR](https://github.com/adr/madr) can carry a specification item ID and is then traced like a requirement
 * **Ignore file**: glob patterns in a `.oftignore` file in the workspace root exclude files from all OFT features, on top of the build output and hidden paths that are excluded by default
 
 The server starts automatically when a supported file is opened. No configuration is required.