You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 7ef25de
Browse filesBrowse the repository at this point in the historyBrowse files
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.
Copy file name to clipboardExpand all lines: README.md
+49-6Lines changed: 49 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -62,10 +62,10 @@ libstdc++'s 2,500 headers, MSVC's 166 STL headers, and a construct-by-construct
62
62
63
63
| Feature | Contents |
64
64
| --- | --- |
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|
66
66
| Hover | The declaration, the deduced type, and the doc comment (Doxygen commands included) |
67
67
| 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 |
69
69
| References, rename, document highlight | Every use in the project, and a rename that edits exactly those |
70
70
| Call hierarchy, document and workspace symbols | Who calls what, and the shape of a file or a project |
71
71
| 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
74
74
**Editing and checking**
75
75
76
76
-**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`,
@@ -89,6 +89,47 @@ libstdc++'s 2,500 headers, MSVC's 166 STL headers, and a construct-by-construct
89
89
`<<<…>>>` launch blocks and the CUDA keywords, and a `[cuda]` section tells the analysis where the toolkit's headers
90
90
are. What a compiler enforces about device code is not modelled.
91
91
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
+
structWidget { 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
+
92
133
## Getting started
93
134
94
135
```bash
@@ -137,9 +178,11 @@ installed. Its output is idiomatic, not byte-identical to clang-format's.
0 commit comments