feat: support macros#1192
Conversation
✨ Highlights
🧾 Changes by Scope
🔝 Top Files
|
Codecov Report❌ Patch coverage is ❌ Your patch check has failed because the patch coverage (86.72%) is below the target coverage (90.00%). You can increase the patch coverage or adjust the target coverage. Additional details and impacted files@@ Coverage Diff @@
## develop #1192 +/- ##
===========================================
+ Coverage 79.20% 79.38% +0.18%
===========================================
Files 308 311 +3
Lines 32332 32644 +312
Branches 6493 6568 +75
===========================================
+ Hits 25607 25914 +307
+ Misses 4355 4335 -20
- Partials 2370 2395 +25
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
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-01 16:15:00 UTC |
gennaroprota
force-pushed
the
feat/support_macros
branch
4 times, most recently
from
2c90a7c to
c1ce891
Compare
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 cppalliance#1127.
gennaroprota
force-pushed
the
feat/support_macros
branch
from
c1ce891 to
a42ad72
Compare
|
Thanks for exploring this. This is a complex issue.
Interesting. I thought it would be easier to have a preprocessor step just for macros.
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).
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. |
3 participants
This adds support for preprocessing macros:
#definedirectives are captured via aclang::PPCallbackssubclass and exposed asMacroSymbolinstances 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.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
@paramblocks are validated.Golden tests also cover the three filter paths (
extract-all: false,include-symbols,exclude-symbols).Closes issue #1127.