Repository navigation
docs: add a Doxygen compatibility page - #1372
Open
gennaroprota wants to merge 5 commits into
Open
gennaroprota wants to merge 5 commits into
gennaroprota wants to merge 5 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.
…ed headings The `auto-brief` option, the configuration and commands pages and the commands registry said that the first sentence of a doc comment becomes its brief, but we take the whole first paragraph. They now say so, as does the `auto-brief` example, and the option's description lists the commands that still set a brief when it is off. Likewise, the synopsis placeholder of a `@seebelow` symbol is `/* see-below */`, not `/* see below */`, and a `@par` with no title takes the first line of its body as the heading, where the registry said it emitted none.
A project migrating from Doxygen had no way to tell which of its commands MrDocs honors short of reading the parser, and many of them are ignored without a warning: some lose their text, others publish text the author meant to hide. The new page lists every Doxygen command by family, with its status, what happens to its text, and the issue that tracks it where there is one. It also lists the comment styles MrDocs accepts and the configuration options that replace Doxygen markup. The commands registry check now also compares the page with the parser, so a command that starts or stops being handled fails CI until its row says so. Fixes cppalliance#1342.
Contributor
✨ Highlights
🧾 Changes by Scope
🔝 Top Files
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1372 +/- ##
========================================
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://1372.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:04:45 UTC |
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.
This PR is stacked on #1371, whose commits it shows until that PR lands; only the last two commits, "docs: correct what the docs say about the brief, see-below and untitled headings" and "docs: add a Doxygen compatibility page", belong to it.
A project migrating from Doxygen couldn't tell which of its commands MrDocs honors, and many are ignored without a warning: some lose their text, others publish text the author meant to hide. A new page under Commands lists every Doxygen command by family, with its status (supported, a different idiom, or not supported), what happens to its text, and the issue that tracks it where there is one, plus the comment styles MrDocs accepts and the options that replace Doxygen markup.
Writing it showed that several docs described the brief as the first sentence of a doc comment, while MrDocs takes the whole first paragraph. The first commit corrects them, along with the
@seebelowplaceholder (/* see-below */) and what an untitled@parproduces.Changes
auto-briefoption's description says "first paragraph" and lists the commands that set a brief when it is off; the config schema follows.Testing
The page check runs in CI with the other registry checks, so a command that starts or stops being handled fails it until its row is updated. The
\condrow is one: it changes when #1367 lands.Documentation
New page commands/doxygen.adoc, linked from the nav, the commands overview and the migration notes. Corrected: the
auto-briefoption, configuration/extraction.adoc, commands/metadata.adoc, migration-notes.adoc and the commands registry.Fixes #1342.