Repository navigation
fix: the commands reference and the parser agree - #1371
Open
gennaroprota wants to merge 3 commits into
Open
gennaroprota wants to merge 3 commits into
gennaroprota wants to merge 3 commits into
Conversation
The commands reference documents `@sa` as an alias of `@see` and `@arg` as an alias of `@li`, but the doc-comment extractor handled neither. Clang gives each of them its own command ID, which reached the branch that ignores unhandled block commands, so the paragraph after the command disappeared without a warning. We now handle them in the same `case` as `@see` and `@li`.
…ence The commands registry, from which the commands reference is generated, documented three forms that don't work. `@link <name> ... @endlink` is a verbatim block in Clang's command table that only HeaderDoc's `@/link` closes, so everything after `@link` becomes a code block. `@strong` is not a command, so `@strong word` renders as the text "strong word". And the quoted text in `@ref <name> "text"` is printed literally after the link. We now document none of them, and the Cross-reference entry says to write `@ref <name>` in place of `@link`. The registry also gains `@dot`, `@msc` and `@startuml`, which the parser already renders as code blocks, and the Footnote Definition and Math Block entries now point to the examples that already show them.
utils/docs/check_commands_registry.py is meant to keep the commands registry in sync with the doc-comment parser, but no CI job ran it, and it had fallen out of step with the registry: it still expected the `node_types` and `preview` fields and the example locations of an earlier layout, and failed with 181 problems, nearly all of them false. We now run it in the utility tests job, with its checks updated to the registry's current shape. It also checked only one direction, that every command the parser handles is documented, which let the registry document `@sa`, `@arg`, `@strong` and `@link` while the parser ignored them. It now also checks that every command a documented syntax names is one the parser handles.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1371 +/- ##
========================================
Coverage 83.21% 83.21%
========================================
Files 35 35
Lines 3670 3670
Branches 845 845
========================================
Hits 3054 3054
Misses 410 410
Partials 206 206
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
An automated preview of the documentation is available at https://1371.mrdocs.prtest2.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-10-30 11:10:19 UTC |
Contributor
✨ Highlights
🧾 Changes by Scope
🔝 Top Files
|
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The commands reference listed
@saand@argas aliases of@seeand@li, but the parser ignored both and dropped their text. It also listed three forms that don't work:@link ... @endlink(Clang closes@linkonly at@/link, so the rest of the comment becomes a code block),@strong(not a command) and@ref <name> "text"(the quoted text is printed literally). Nothing caught this, because utils/docs/check_commands_registry.py, meant to keep the registry and the parser in sync, never ran in CI and no longer matched the registry's shape. Found while writing the Doxygen compatibility page for #1342.Changes
@sais handled like@see, and@arglike@li.@command a registry syntax names to be one the parser handles.Testing
The new fixtures pin both aliases, and the CI step fails whenever the registry documents a command the parser ignores, or the parser handles a command the registry doesn't document.
Documentation
The commands registry, from which the commands reference is generated, drops the three false forms (the Cross-reference entry points
@linkusers to@ref <name>), adds@dot,@mscand@startuml, which the parser already renders as code blocks, and gives the Footnote Definition and Math Block entries their examples.