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 bc113ff
Browse filesBrowse the repository at this point in the historyBrowse files
readme: @see is a symbol reference, and @code is code
The documentation section now says what the server does with the two shapes it gained: a command that takes a
reference (`@see`, `@sa`, `@ref`, `@overload`, `@extends`, `@implements`, `@cite`) completes the program's names
rather than the documented declaration's parameters, and an `@code` block is coloured and completed as code — with the
marker-stripping detail that makes it work.
The reference table's *definition* row now says a macro's reference jumps to its `#define`, and the decisions list
gains the one this work made: a reference's body is prose, because a target never holds a space.
Copy file name to clipboardExpand all lines: README.md
+18-6Lines changed: 18 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -100,33 +100,45 @@ from the buffer the reader is editing.
100
100
the table are vocabulary the server knows:
101
101
102
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);
103
+
-**completion** offers the command names (`/// @par` → `param`, `tparam`, `par`, `paragraph`); after a command that
104
+
takes a name, the parameters of the declaration being documented (`@param |` → its parameters); and after one that
105
+
takes a **reference** — `@see`, `@sa`, `@ref`, `@overload`, `@extends`, `@implements`, `@cite` — the program's
106
+
names, exactly as a `` [`…`] `` link gets them;
105
107
-**semantic tokens** draw a command as `decorator`, which a client can remap on its own — the cppls extension draws
106
108
`keyword.doxygen` from it;
107
109
- a command's *body* is the reader's, and the server does not colour it.
108
110
109
-
**Symbol references.** Rust's intra-doc link, in a C++ comment:
111
+
**Code blocks.**`@code` … `@endcode` is an example of code, not prose, and it is treated as one: the block's
112
+
keywords and resolvable names are coloured like the code around it, and completion inside the block offers what a
113
+
statement offers — keywords and snippets included. The body is read **per line with the comment marker removed**, so
114
+
`/// int main() { return 0; }` lexes as code rather than as another comment.
115
+
116
+
**Symbol references.** Rust's intra-doc link, in a C++ comment — and Doxygen's own spelling of the same thing:
110
117
111
118
```cpp
112
119
/// See [`Widget::grow`] for the rule, [`std::vector`] for the container, and [`grow()`] for the call.
120
+
/// @see Widget::grow
113
121
structWidget { void grow(int by); };
114
122
```
115
123
116
124
| Position | What happens |
117
125
| --- | --- |
118
126
| 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
127
| 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 |
128
+
| definition | Jumps to the declaration; a macro's reference jumps to its `#define`, which is the only place a reader can go for one |
129
+
| completion | The names this file can see — and only names, never a snippet: a reference takes a symbol |
130
+
131
+
Both spellings are one question, answered in one place (`cpp_code_analysis::doc`), which is why the colour, the card
132
+
and the jump cannot disagree about what a reference names.
122
133
123
-
Three details worth stating, because they are decisions rather than accidents:
134
+
Four details worth stating, because they are decisions rather than accidents:
124
135
125
136
* **Only the backticked form.** `[target]` without the backticks is what Rust also accepts, and in a C++ comment it
126
137
collides with the most ordinary prose there is: `arr[i]` and `matrix[row][col]`. The backtick is the whole
127
138
disambiguator, and a target with whitespace in it is a title rather than a link.
128
139
* **`()` and `!` are punctuation, not part of the name.** `` [`grow()`] `` says "this is a call" and `` [`MAX_SIZE!`] ``
129
140
says "this is a macro"; both are trimmed before the lookup, and the range still covers what was written.
141
+
* **A reference's body is prose.** `@see Foo for the rule` names `Foo`: a target never holds a space.
130
142
* **Prose offers nothing.** A cursor anywhere else in a documentation comment completes nothing at all — a comment is
131
143
not a place a C++ name goes — while ordinary identifiers still get the client's own colour.
0 commit comments