Skip to content

fix: the commands reference and the parser agree #1371

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gennaroprota wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

fix: the commands reference and the parser agree #1371

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a9918d5
fix: @sa and @arg keep their text
gennaroprota Oct 29, 2026
0b74fe0
docs: list only the commands the parser handles in the commands refer…
gennaroprota Oct 29, 2026
33d988f
ci: check the commands registry against the parser
gennaroprota Oct 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/ci-utility-tests.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,9 @@ jobs:
- name: Check bootstrap options partial is up to date
run: python3 ./utils/docs/generate_bootstrap_options.py --check

- name: Check commands registry is in sync with the parser
run: python3 ./utils/docs/check_commands_registry.py

# When the Coverage matrix entry was skipped because the develop cache is
# warm, fetch develop's LCOV report and re-upload it tagged with the PR's
# commit SHA. Codecov sees zero patch lines and unchanged project totals,
Expand Down
30 changes: 15 additions & 15 deletions docs/modules/ROOT/partials/commands-registry.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,14 +96,17 @@
"kind": "Block",
"syntaxes": [
"@code[{.lang}] ... @endcode",
"@verbatim ... @endverbatim"
"@verbatim ... @endverbatim",
"@dot ... @enddot",
"@msc ... @endmsc",
"@startuml ... @enduml"
],
"partial": "commands/code-block.adoc",
"examples": [
"commands/code-block"
],
"see_also": [],
"description": "Inserts a block of preformatted code into the documentation.\nEverything between the opening and closing tags is preserved verbatim, including whitespace and indentation.\n\n`@code` and `@verbatim` produce the same output.\nUse `@code` for source code and `@verbatim` for other preformatted text, though MrDocs treats them identically.",
"description": "Inserts a block of preformatted code into the documentation.\nEverything between the opening and closing tags is preserved verbatim, including whitespace and indentation.\n\n`@code` and `@verbatim` produce the same output.\nUse `@code` for source code and `@verbatim` for other preformatted text, though MrDocs treats them identically.\n\n`@dot`, `@msc`, and `@startuml` also produce a code block, tagged with the language `dot`, `msc`, and `plantuml` respectively.",
"parameters": [
{
"name": "lang",
Expand All @@ -113,7 +116,7 @@
{
"name": "code",
"type": "Code",
"description": "The verbatim source between the opening command and `@endcode`/`@endverbatim`."
"description": "The verbatim source between the opening command and its closing command."
}
]
},
Expand Down Expand Up @@ -216,7 +219,9 @@
"[^label]: text"
],
"partial": "commands/footnote-definition.adoc",
"examples": [],
"examples": [
"commands/footnote"
],
"see_also": [
"Footnote Reference"
],
Expand All @@ -243,7 +248,9 @@
"\\f[ expression \\f]"
],
"partial": "commands/math-block.adoc",
"examples": [],
"examples": [
"commands/math"
],
"see_also": [
"Math"
],
Expand Down Expand Up @@ -582,7 +589,6 @@
"**text**",
"__text__",
"@b <word>",
"@strong <word>",
"<strong>text</strong>"
],
"partial": "commands/strong.adoc",
Expand All @@ -592,7 +598,7 @@
"see_also": [
"Emphasis"
],
"description": "Renders its content in bold (strong) style.\nUse `**` or `__` around the bold text.\nThe Doxygen commands `@b` and `@strong` bold the single word that follows them.",
"description": "Renders its content in bold (strong) style.\nUse `**` or `__` around the bold text.\nThe Doxygen command `@b` bolds the single word that follows it.",
"parameters": [
{
"name": "word",
Expand Down Expand Up @@ -816,8 +822,7 @@
"heading": "Cross-reference",
"kind": "Inline",
"syntaxes": [
"@ref <name> [\"text\"]",
"@link <name> ... @endlink"
"@ref <name>"
],
"partial": "commands/cross-reference.adoc",
"examples": [
Expand All @@ -827,17 +832,12 @@
"Link",
"See-also"
],
"description": "Creates a cross-reference to another documented symbol.\nThe `@ref` command takes a symbol name (optionally namespace-qualified) and produces a link to that symbol's documentation page.\nQualified names use `::` separators (e.g., `@ref A::f1`, `@ref ::A::f1`).\nOperator names are supported (e.g., `@ref F::operator+`).",
"description": "Creates a cross-reference to another documented symbol.\nThe `@ref` command takes a symbol name (optionally namespace-qualified) and produces a link to that symbol's documentation page.\nQualified names use `::` separators (e.g., `@ref A::f1`, `@ref ::A::f1`).\nOperator names are supported (e.g., `@ref F::operator+`).\n\nDoxygen's `@link <name> text @endlink` is not supported: Clang closes `@link` only at `@/link`, so `@endlink` never ends it and the rest of the comment becomes a code block. Write `@ref <name>` instead.",
"parameters": [
{
"name": "name",
"type": "Symbol",
"description": "Qualified name of the symbol to link to."
},
{
"name": "text",
"type": "Text",
"description": "Optional display text for the link."
}
]
},
Expand Down
2 changes: 2 additions & 0 deletions src/mrdocs/AST/ExtractDocComment.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1717,6 +1717,7 @@ class DocCommentVisitor
return;
}
case T::KCI_li:
case T::KCI_arg:
{
if (jd_.Document.empty() || !jd_.Document.back()->isList())
{
Expand All @@ -1735,6 +1736,7 @@ class DocCommentVisitor
return;
}
case T::KCI_see:
case T::KCI_sa:
{
auto see = parseBlock(std::in_place_type<doc::SeeBlock>);
jd_.sees.push_back(std::move(see));
Expand Down
13 changes: 13 additions & 0 deletions tests/golden/fixtures/javadoc/lists/arg.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
/** A function

@arg Point 1
@arg Point 2

Another paragraph.

@li Point 3
@arg Point 4
@li Point 5
\arg Point 6
*/
void f();
156 changes: 156 additions & 0 deletions tests/golden/fixtures/javadoc/lists/arg.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
<?xml version="1.0" encoding="UTF-8"?>
<mrdocs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://mrdocs.com/docs/mrdocs/master/_attachments/schemas/generators/mrdocs.rng">
<namespace>
<anchor>index</anchor>
<kind>namespace</kind>
<id>4ZrjxJnU1LA5xSyrWMNuXTvSYKwt</id>
<extraction>regular</extraction>
<members>
<functions>3WB9tVatMdT8usB7kG91HHDMUYwU</functions>
</members>
</namespace>
<function>
<name>f</name>
<anchor>f</anchor>
<loc>
<loc>
<location>
<shortPath>arg.cpp</shortPath>
<sourcePath>arg.cpp</sourcePath>
<lineNumber>13</lineNumber>
<columnNumber>1</columnNumber>
<documented/>
</location>
</loc>
</loc>
<kind>function</kind>
<id>3WB9tVatMdT8usB7kG91HHDMUYwU</id>
<extraction>regular</extraction>
<parent>4ZrjxJnU1LA5xSyrWMNuXTvSYKwt</parent>
<doc>
<document>
<list>
<kind>list</kind>
<items>
<listItem>
<blocks>
<paragraph>
<kind>paragraph</kind>
<children>
<text>
<kind>text</kind>
<literal>Point 1</literal>
</text>
</children>
</paragraph>
</blocks>
</listItem>
<listItem>
<blocks>
<paragraph>
<kind>paragraph</kind>
<children>
<text>
<kind>text</kind>
<literal>Point 2</literal>
</text>
</children>
</paragraph>
</blocks>
</listItem>
</items>
<listKind>unordered</listKind>
</list>
<paragraph>
<kind>paragraph</kind>
<children>
<text>
<kind>text</kind>
<literal>Another paragraph.</literal>
</text>
</children>
</paragraph>
<list>
<kind>list</kind>
<items>
<listItem>
<blocks>
<paragraph>
<kind>paragraph</kind>
<children>
<text>
<kind>text</kind>
<literal>Point 3</literal>
</text>
</children>
</paragraph>
</blocks>
</listItem>
<listItem>
<blocks>
<paragraph>
<kind>paragraph</kind>
<children>
<text>
<kind>text</kind>
<literal>Point 4</literal>
</text>
</children>
</paragraph>
</blocks>
</listItem>
<listItem>
<blocks>
<paragraph>
<kind>paragraph</kind>
<children>
<text>
<kind>text</kind>
<literal>Point 5</literal>
</text>
</children>
</paragraph>
</blocks>
</listItem>
<listItem>
<blocks>
<paragraph>
<kind>paragraph</kind>
<children>
<text>
<kind>text</kind>
<literal>Point 6</literal>
</text>
</children>
</paragraph>
</blocks>
</listItem>
</items>
<listKind>unordered</listKind>
</list>
</document>
<brief>
<kind>brief</kind>
<children>
<text>
<kind>text</kind>
<literal>A function</literal>
</text>
</children>
</brief>
</doc>
<returnType>
<named>
<kind>named</kind>
<name>
<identifier>
<kind>identifier</kind>
<identifier>void</identifier>
</identifier>
</name>
<fundamentalType>void</fundamentalType>
</named>
</returnType>
<funcClass>normal</funcClass>
</function>
</mrdocs>
99 changes: 99 additions & 0 deletions tests/golden/fixtures/javadoc/see/sa.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
= Reference
:mrdocs:

[#index]
== Global namespace

=== Namespaces

[cols="1"]
|===
| Name
| link:#A[`A`]
|===


=== Functions

[cols="1,4"]
|===
| Name| Description
| link:#f[`f`]
| A function
| link:#g[`g`]
| Another function
|===


[#A]
== A

=== Functions

[cols="1,4"]
|===
| Name| Description
| link:#A-h[`h`]
| A function in a namespace
|===


[#A-h]
== link:#A[A]::h

A function in a namespace

=== Synopsis

Declared in `&lt;sa&period;cpp&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
void
h();
----

[#f]
== f

A function

=== Synopsis

Declared in `&lt;sa&period;cpp&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
void
f();
----

=== See Also

g

g

A&colon;&colon;h

g

link:#g[`g`]

[#g]
== g

Another function

=== Synopsis

Declared in `&lt;sa&period;cpp&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
void
g();
----


[.small]#Created with https://www.mrdocs.com[MrDocs]#
Loading
Loading