Skip to content

Commit 7ef25de

Browse files
committed
readme: what the documentation comments support
Two sections, because the two are different features that share a comment. **Doxygen commands** — the four forms (\///\, \//!\, \/**\, \/*!\), the vocabulary the server knows, and what each LSP answer does with it: hover explains a command and renders a declaration's own comment; completion offers the command names and, after a command that takes one, the documented declaration's parameters; semantic tokens draw a command as \decorator\, which a client can remap. **Symbol references** — Rust's \[\Widget::grow\]\ in a C++ comment: coloured as the declaration it names (and not coloured when nothing declares it), hover card, jump (a macro's jumps to its \#define\), and completion of the names the file can see. The three decisions are stated because they are decisions: only the backticked form (\[target]\ collides with \�rr[i]\), \()\ and \!\ are punctuation rather than part of the name, and prose completes nothing. Every claim is one measured in this session: \/// @Par\ → \param\/\ param\/\par\/\paragraph\; \/// @PARAM \ → the declaration's own \x\/\y\; hover on \@PARAM\ → its sentence; \/// See [\Wid\ → \Widget\/\ \/\grow\ and no snippet; \/// Hello wi\ → nothing.
1 parent 523c2b2 commit 7ef25de

1 file changed

Lines changed: 49 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 49 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -62,10 +62,10 @@ libstdc++'s 2,500 headers, MSVC's 166 STL headers, and a construct-by-construct
6262

6363
| Feature | Contents |
6464
| --- | --- |
65-
| Completion | Members after `.` / `->` / `::`, through pointers, smart pointers, bases and instantiated templates; names in scope |
65+
| Completion | Members after `.` / `->` / `::`, through pointers, smart pointers, bases and instantiated templates; names in scope; the Doxygen vocabulary and a symbol reference's target inside a documentation comment |
6666
| Hover | The declaration, the deduced type, and the doc comment (Doxygen commands included) |
6767
| Signature help | The parameter list being filled in, from the same facts the call is checked against |
68-
| Definition / type definition / implementation | Where a name, its type, or the override of a virtual function is written |
68+
| Definition / type definition / implementation | Where a name, its type, or the override of a virtual function is written — including a `` [`symbol`] `` a documentation comment refers to |
6969
| References, rename, document highlight | Every use in the project, and a rename that edits exactly those |
7070
| Call hierarchy, document and workspace symbols | Who calls what, and the shape of a file or a project |
7171
| Folding, selection range | Blocks, comments and regions; the syntactic unit around the cursor |
@@ -74,8 +74,8 @@ libstdc++'s 2,500 headers, MSVC's 166 STL headers, and a construct-by-construct
7474
**Editing and checking**
7575

7676
- **Inlay hints** — the deduced type of `auto` and structured bindings, parameter names at a call.
77-
- **Semantic tokens** — names, types, keywords, documentation commands, and format strings (`formatSpecifier`,
78-
`formatArgument`, `formatConversion`, `formatEscape`).
77+
- **Semantic tokens** — names, types, keywords, documentation commands and symbol references, and format strings
78+
(`formatSpecifier`, `formatArgument`, `formatConversion`, `formatEscape`).
7979
- **Code actions** — quick fixes from the same diagnostics.
8080
- **Diagnostics** — `textDocument/diagnostic` for pull-capable clients, otherwise versioned
8181
`textDocument/publishDiagnostics`, 26 codes: `syntax-error`, `include-not-found`,
@@ -89,6 +89,47 @@ libstdc++'s 2,500 headers, MSVC's 166 STL headers, and a construct-by-construct
8989
`<<<…>>>` launch blocks and the CUDA keywords, and a `[cuda]` section tells the analysis where the toolkit's headers
9090
are. What a compiler enforces about device code is not modelled.
9191

92+
## Documentation comments
93+
94+
A documentation comment is **a language of its own**, not prose the analysis skips. `///` and `//!` mark one line;
95+
`/**` and `/*!` open a block that stays documentation until its `*/`. Everything below works in all four, and in the
96+
file's own text — a comment produces no tokens in the cooked reading, so every one of these questions is answered
97+
from the buffer the reader is editing.
98+
99+
**Doxygen commands.** `@brief`, `@param`, `@return`, `@tparam`, `@exception`, `@see`, `@code`, `@name` and the rest of
100+
the table are vocabulary the server knows:
101+
102+
- **hover** on a command explains it, and a declaration's own comment is rendered in its card;
103+
- **completion** offers the command names (`/// @par` → `param`, `tparam`, `par`, `paragraph`) and, after a command
104+
that takes one, the names of the declaration being documented (`@param |` → its parameters);
105+
- **semantic tokens** draw a command as `decorator`, which a client can remap on its own — the cppls extension draws
106+
`keyword.doxygen` from it;
107+
- a command's *body* is the reader's, and the server does not colour it.
108+
109+
**Symbol references.** Rust's intra-doc link, in a C++ comment:
110+
111+
```cpp
112+
/// See [`Widget::grow`] for the rule, [`std::vector`] for the container, and [`grow()`] for the call.
113+
struct Widget { void grow(int by); };
114+
```
115+
116+
| Position | What happens |
117+
| --- | --- |
118+
| The target | Coloured as the declaration it names — a function, a type, a macro — and **not** coloured when nothing declares it: a colour would say the name is known |
119+
| hover | The declaration's card, the same one a name gets |
120+
| definition | Jumps to the declaration; a macro's link jumps to its `#define`, which is the only place a reader can go for one |
121+
| completion | The names this file can see — and only names, never a snippet: a link takes a symbol |
122+
123+
Three details worth stating, because they are decisions rather than accidents:
124+
125+
* **Only the backticked form.** `[target]` without the backticks is what Rust also accepts, and in a C++ comment it
126+
collides with the most ordinary prose there is: `arr[i]` and `matrix[row][col]`. The backtick is the whole
127+
disambiguator, and a target with whitespace in it is a title rather than a link.
128+
* **`()` and `!` are punctuation, not part of the name.** `` [`grow()`] `` says "this is a call" and `` [`MAX_SIZE!`] ``
129+
says "this is a macro"; both are trimmed before the lookup, and the range still covers what was written.
130+
* **Prose offers nothing.** A cursor anywhere else in a documentation comment completes nothing at all — a comment is
131+
not a place a C++ name goes — while ordinary identifiers still get the client's own colour.
132+
92133
## Getting started
93134
94135
```bash
@@ -137,9 +178,11 @@ installed. Its output is idiomatic, not byte-identical to clang-format's.
137178

138179
## Documentation
139180

140-
[`docs/cpp-support.md`](docs/cpp-support.md)
181+
[`docs/cpp-support.md`](docs/cpp-support.md) ·
141182
[`docs/c-support.md`](docs/c-support.md) ·
142-
[`docs/configuration.md`](docs/configuration.md)
183+
[`docs/configuration.md`](docs/configuration.md) ·
184+
[`docs/open-questions.md`](docs/open-questions.md) — what is measured and **not** fixed, with the evidence
185+
143186
## License
144187

145188
MIT. See [`LICENSE`](LICENSE).

0 commit comments

Comments
 (0)