feat: support macros

[gennaroprota]

This adds support for preprocessing macros: #define directives are captured via a clang::PPCallbacks subclass and exposed as MacroSymbol instances at the corpus root (macros aren't in any C++ scope, so they sit alongside the global namespace rather than under it).

Doc-comment association: Clang doesn't link comments to macros, so we look up a preceding doc-comment by source location. A comment is attached only when the lines between it and the directive are blank.

Filters apply to macros, too:

• extract-all: when off, undocumented macros are dropped.
• exclude-symbols, include-symbols, implementation-defined, see-below: matched against the macro name.
• File-pattern filters: matched against the directive's source location.

Schema additions: <macro> is a new top-level element in mrdocs.rnc, sibling of <namespace>, with <source> carrying the verbatim definition (modulo a minor normalization).

New output pages: multipage mode now produces macros.{ext} at the output root, listing every macro with a link to its per-symbol page. The global-namespace page gains a "See also: Macros" navigation hint at the bottom (multipage-only) so the new page is discoverable.

Macro @param blocks are validated.

Golden tests also cover the three filter paths (extract-all: false, include-symbols, exclude-symbols).

Closes issue #1127.

---

Adds first-class support for preprocessing macros. #define directives are captured through a clang::PPCallbacks subclass (MacroCollector) and surfaced as MacroSymbol instances at the corpus root — macros aren't in any C++ scope, so they sit alongside the global namespace rather than under it. Closes #1127.

Several pieces fit together:

• Doc-comment association: Clang does not link comments to macros, so the doc-comment finalizer looks up a preceding doc-comment by source location. A comment is attached only when the lines between it and the #define directive are blank, matching how a contributor would intuitively expect it to bind.
• Filters apply to macros too: extract-all (when off, undocumented macros are dropped), exclude-symbols / include-symbols / implementation-defined / see-below (matched against the macro name), and file-pattern filters (matched against the directive's source location).
• Schema additions: <macro> becomes a new top-level element in mrdocs.rnc, sibling of <namespace>, with <source> carrying the verbatim definition (modulo a minor normalization).
• Output pages: Multipage mode produces macros.{ext} at the output root, listing every macro with a link to its per-symbol page. The global-namespace page gains a "See also: Macros" navigation hint at the bottom (multipage-only) so the new page is discoverable.
• @param validation: Macro @param blocks are validated like for functions.

Changes

• Source: New src/lib/AST/MacroCollector.{cpp,hpp} (the PPCallbacks subclass) wired into ASTVisitor.{cpp,hpp} and ASTAction.cpp. New include/mrdocs/Metadata/Symbol/Macro.hpp defining MacroSymbol; Metadata.hpp, Symbol/SymbolKind.hpp, and Symbol/SymbolNodes.inc extended with the new symbol kind; include/mrdocs/Corpus.hpp and src/lib/Corpus.cpp expose macros at the corpus root. Metadata/Finalizers/DocCommentFinalizer.cpp carries the doc-comment-by-source-location association and macro-@param validation. Handlebars generators (Gen/hbs/Builder.cpp, HandlebarsGenerator.cpp, SinglePageVisitor.cpp) emit macro pages and the navigation hint on the global-namespace page; new share/mrdocs/addons/generator/{adoc,html}/layouts/macros-index.*.hbs and share/mrdocs/addons/generator/common/partials/symbol/signature/macro.hbs are the template-side pieces.
• Tests: All exercised through golden tests; no separate unit tests added.
• Golden tests: Five new fixture sets under test-files/golden-tests/symbols/macro/ (macros, macros-edge-cases, macros-extraction-modes, macros-embedded, macros-multi-file) cover the happy path, edge cases, extraction modes, multi-file inputs, and macros embedded in other constructs. Three filter-coverage fixtures under test-files/golden-tests/config/: extract-all/no-extract-all-macros, include-symbols/macros-allowlist, exclude-symbols/macros-excluded. One multipage fixture under test-files/golden-tests/config/multipage/multipage-macros proves the new macros.{ext} page and per-symbol pages are generated.
• Build: mrdocs.rnc extended with the new <macro> element and its children.
• Breaking changes: None at the user-facing CLI; existing config behavior is unchanged for projects with no macros. The XML/HBS schema gains a new top-level <macro> element — downstream tooling that consumes mrdocs output and assumes the previous set of top-level elements will need to add a clause for macros.

Testing

• Nine golden-test trees added under test-files/golden-tests/symbols/macro/ and test-files/golden-tests/config/ are the verification layer. Each runs the full pipeline (parse → preprocess capture → finalize → generate) against fixed .cpp inputs and asserts the resulting .xml / .html / .adoc output byte-for-byte. The fixtures cover the main flow, edge cases, extraction modes, multi-file inputs, embedded macros, multipage output, and each of the three filter paths individually.
• No CI workflow changes needed — the existing golden-test job runs all of test-files/golden-tests/ on every build, so the new trees stay covered automatically going forward.

Documentation

No user-facing documentation is added in this PR. The schema (mrdocs.rnc) is updated for the new <macro> element, but a how-to / reference page under docs/modules/ROOT/pages/ describing macro support — what gets captured, how the doc-comment association rule works, how the filters apply, and the new multipage macros page — is worth adding as a follow-up so the feature is discoverable for users browsing the documentation rather than the schema.

[github-actions]

⚠️ Warnings

Warning

This PR looks like it adds a new feature but does not update any documentation. Please document the new functionality under docs/, or add a no-docs-needed label / [skip danger docs] marker if not applicable.

✨ Highlights

• 🧪 New golden tests added

🧾 Changes by Scope

Scope	Lines Δ%	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🥇 Golden Tests	78%	3800	3800	-	53	53	-	-	-
🛠️ Source	22%	1087	1062	25	35	6	29	-	-
🏗️ Build	<1%	13	13	-	1	-	1	-	-
Total	100%	4900	4875	25	89	59	30	-	-

Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)

🔝 Top Files

• test-files/golden-tests/symbols/macro/macros.xml (Golden Tests): 649 lines Δ (+649 / -0)
• test-files/golden-tests/symbols/macro/macros.html (Golden Tests): 531 lines Δ (+531 / -0)
• test-files/golden-tests/symbols/macro/macros.adoc (Golden Tests): 397 lines Δ (+397 / -0)

Generated by 🚫 dangerJS against 32e9ccf

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.12%. Comparing base (5ca01a2) to head (32e9ccf).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1192   +/-   ##
========================================
  Coverage    82.12%   82.12%           
========================================
  Files           33       33           
  Lines         3149     3149           
  Branches       734      734           
========================================
  Hits          2586     2586           
  Misses         387      387           
  Partials       176      176           

Flag	Coverage Δ
bootstrap	82.12% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cppalliance-bot]

An automated preview of the documentation is available at https://1192.mrdocs.prtest2.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-05-04 06:09:45 UTC

[alandefreitas]

Thanks for exploring this. This is a complex issue.

This adds support for preprocessing macros: #define directives are captured via a clang::PPCallbacks

Interesting. I thought it would be easier to have a preprocessor step just for macros.

so we look up a preceding doc-comment by source location

This seems extremely problematic because the counterexamples where it doesn't work would be kind of obvious. Clang doesn't even attach comments to anything if there's not close to a symbol, which is probably the case when there's a macro.

My intuition is we can't really implement this feature unless clang wants to attach comments to macros or we implement our own parser (which we also intend to).

Filters apply to macros, too

How do these compare to doxygen? Shouldn't we have some special options for macros? I'm not sure. I assume macros are somewhat special in terms of what's typically hidden or shown, but I haven't thought too much about it.

I think @mizvekov would probably be more qualified to review this issue and PR.

[gennaroprota]

This adds support for preprocessing macros: #define directives are captured via a clang::PPCallbacks

Interesting. I thought it would be easier to have a preprocessor step just for macros.

Hmm... I'm listening for MacroDefined events on the preprocessor instance that Clang is already running for the AST pass, which seems natural.

so we look up a preceding doc-comment by source location

This seems extremely problematic because the counterexamples where it doesn't work would be kind of obvious. Clang doesn't even attach comments to anything if there's not close to a symbol, which is probably the case when there's a macro.

My intuition is we can't really implement this feature unless clang wants to attach comments to macros or we implement our own parser (which we also intend to).

Why? The current condition for accepting a preceding comment is that it is separated from the macro definition by blank lines only (and it is a doc-comment). We could tighten that to "no lines at all between the comment and the macro definition"; or maybe we can accept at most one line that is blank.

Filters apply to macros, too

How do these compare to doxygen? Shouldn't we have some special options for macros? I'm not sure. I assume macros are somewhat special in terms of what's typically hidden or shown, but I haven't thought too much about it.

I surveyed Doxygen's options. They are:

• ENABLE_PREPROCESSING/MACRO_EXPANSION: master switches for Doxygen's preprocessor. MrDocs always runs a preprocessing pass.

• PREDEFINED: pre-defines macros. MrDocs has the defines config option.

• EXPAND_ONLY_PREDEF/EXPAND_AS_DEFINED: restrict macro expansion to predefined macros plus those of an explicit list. MrDocs has no equivalent.

• SKIP_FUNCTION_MACROS: heuristic that drops some function-like macros; it exists to keep some macros from confusing the Doxygen parser.

Would you like to add any of these to MrDocs?

[alandefreitas]

Why? The current condition for accepting a preceding comment is that it is separated from the macro definition by blank lines only (and it is a doc-comment).

Oh... OK. That's good. I had only made the comment because your previous comment only said by "source location", which implied there could be content between the macro and the source location. But what you mentioned sounds great.

Would you like to add any of these to MrDocs?

No. Great survey. Thanks. I think my original comment was more specific about filtering macros. But that’s great. If there are no specific options to filter macros by name, let's just go with what we have. Sounds great.

One more question: if clang doesn't attach comments to macros like it does to the Decls, how do we find these comments? Do we look for comments attached to something else that should be attached to macros and then move them to the macros? I don't really understand it yet.

[gennaroprota]

Good question. Clang's ASTContext stores every comment it lexes in ASTContext::Comments (which, despite the type name RawCommentList, is really a per-file table). In the case of declarations, it also builds a second-layer mapping (Decl -> RawComment) by walking from each Decl's location backward with some proximity rules; in the case of macros it doesn't, but the underlying per-file map still has every comment in the TU, including the ones above #defines. We just do the location-based lookup ourselves. This logic is in findPrecedingMacroComment, in ASTVisitor.cpp.