refactor(metadata): integrate Boost.Describe #1130

gennaroprota · 2025-12-09T11:49:20Z

This introduces Boost.Describe and Boost.Mp11 and applies them across metadata types (symbols, enums, inline elements) to replace hand-written sequences of io.map() calls with reflection-based code. This improves maintainability without altering the public API or user-facing features.

@alandefreitas: Please have a look at normalizeMemberName() in SymbolDescribeMapper.hpp: Some names are special-cased there. If you prefer, I can remove the special cases and modify the Handlebars templates to use the canonical names.

github-actions · 2025-12-09T11:49:41Z

🚧 Danger.js checks for MrDocs are experimental; expect some rough edges while we tune the rules.

⚠️ Warnings

Warning

Add a brief note about how this change was tested (or why tests are not needed).

🧾 Changes by Scope

Scope	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🛠️ Source	1978	1424	554	54	8	46	-	-
🤝 Third-party	168	168	-	6	6	-	-	-
⚙️ CI	42	41	1	1	-	1	-	-
📄 Docs	8	8	-	1	-	1	-	-
🏗️ Build / Toolchain	5	5	-	1	-	1	-	-
Total	2201	1646	555	63	14	49	-	-

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

🔝 Top Files

src/lib/Support/Reflection/Reflection.cpp (Source): 507 lines Δ (+507 / -0)
src/lib/Support/Reflection/MapReflectedType.hpp (Source): 259 lines Δ (+259 / -0)
include/mrdocs/Dom/LazyObject.hpp (Source): 234 lines Δ (+138 / -96)

Generated by 🚫 dangerJS against 1425bdf

include/mrdocs/Metadata/Symbol/EnumToString.hpp

include/mrdocs/Metadata/DocComment/Inline/ImageInline.hpp

include/mrdocs/Metadata/Symbol/Namespace.hpp

alandefreitas

Great job! 👏😀🎉

alandefreitas · 2025-12-09T18:52:14Z

.github/workflows/ci.yml

+        uses: alandefreitas/cpp-actions/cmake-workflow@v1.8.12
+        with:
+          source-dir: ../third-party/boost_describe
+          git-repository: https://github.com/boostorg/describe


Setting the url is cheaper in this case.

What do you mean?

CMakeLists.txt

include/mrdocs/Metadata/Expression.hpp

include/mrdocs/Metadata/Symbol/EnumToString.hpp

include/mrdocs/Metadata/Symbol/Namespace.hpp

include/mrdocs/Metadata/Symbol/NamespaceAlias.hpp

src/lib/Support/Reflection/MapReflectedType.hpp

src/lib/Metadata/Source.cpp

alandefreitas · 2025-12-10T01:50:19Z

@alandefreitas: Please have a look at normalizeMemberName() in SymbolDescribeMapper.hpp: Some names are special-cased there. If you prefer, I can remove the special cases and modify the Handlebars templates to use the canonical names.

Sorry. I forgot to answer this one. 😬

Yes. We're going to use canonical names for everything sooner or later. Since you already made the effort to split this into two tasks, we can do that later rather than sooner. Reflection will enable all kinds of simplifications in the code from now on.

I leave it up to you, though.

alandefreitas · 2025-12-13T00:10:28Z

Sometimes we get conflicts if we don't rename things for Handlebars, as you notice with "class" and "functionClass", etc. This is because of how handlebars works with recursion, and it's very annoying. I don't know if it solves your problem, but one solution I was going to propose at some point is adding an "@meta" key to all objects to describe the class name, etc (this can also help with other problems we've been having). This way, we would have the proper information to make the distinction in handlebars.

codecov · 2025-12-24T12:04:10Z

Codecov Report

❌ Patch coverage is 91.82390% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.49%. Comparing base (6cee4af) to head (1425bdf).

Files with missing lines	Patch %	Lines
src/lib/Support/Reflection/Reflection.cpp	83.87%	10 Missing ⚠️
include/mrdocs/Dom/LazyObject.hpp	95.45%	1 Missing ⚠️
src/lib/Support/Reflection/EnumToString.hpp	85.71%	1 Missing ⚠️
src/lib/Support/Reflection/MapReflectedType.hpp	97.50%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1130      +/-   ##
===========================================
+ Coverage    86.43%   86.49%   +0.06%     
===========================================
  Files          323      326       +3     
  Lines        23958    23828     -130     
===========================================
- Hits         20707    20609      -98     
+ Misses        3251     3219      -32

☔ 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 · 2026-01-07T13:07:53Z

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

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

2026-01-16 17:32:44 UTC

alandefreitas

That's really nice. Most comments I left are either compliments or suggestions for future issues. Regarding your question about generalizing the process and variable names, I would also leave that to another smaller issue.

.github/workflows/ci.yml

docs/mrdocs.yml

include/mrdocs/Dom/LazyArray.hpp

include/mrdocs/Support/EnumToString.hpp

src/lib/Support/Reflection/Reflection.cpp

alandefreitas · 2026-01-07T22:43:02Z

src/lib/Support/Reflection/Reflection.cpp

+{
+    MRDOCS_ASSERT(domCorpus);
+    mapReflectedType(io, I, domCorpus);
+    io.map("class", std::string("symbol"));


We're going to need another proper solution to this (another issue). Handlebars often need information about the class and so on, and these often clash with object members no matter what name we decide for the key. I was thinking of something like "@meta" where we would always provide a lazy representation of the class name, etc, to handlebars.

alandefreitas · 2026-01-07T22:43:49Z

src/lib/Support/Reflection/Reflection.cpp

+    doc::ImageInline const& I,
+    DomCorpus const* domCorpus)
+{
+    tag_invoke(t, io, dynamic_cast<doc::Inline const&>(I), domCorpus);


Boost.Describe can also iterate the base classes in the function.

src/lib/Support/Reflection/Reflection.cpp

alandefreitas · 2026-01-07T22:49:24Z

src/lib/Support/Reflection/Reflection.hpp

That's really nice. Is there a way to reduce compile time (or address another issue) so that any TU that includes this header doesn't have to parse all metadata-related headers? I don't know if there's a reasonable way to forward declare the struct descriptions.

Hmm, I'm pretty sure the BOOST_DESCRIBE_xxx() macros require a defining declaration. Or did you have something specific in mind to work around this?

I'm not sure I understand. Do you mean a forward declaration for the specializations those macros define is something that wouldn't work? I was thinking just of forward declarations so everything could be encapsulated. And of course we would replicate the macro that generates the forward declarations we need. Instead of completely describing something, we would just forward declare the classes that describing something generates. We could also have a macro that forward declares whatever classes describing would create. Doesn't that work?

I've not dug into the implementation details of Boost.Describe, but I guess it generates hidden internal structures that use pointers to members, and one cannot take a pointer to member of an incomplete type.

However, the current design already provides, I think, the separation you are asking about:

The struct definitions live in public headers.

The BOOST_DESCRIBE_STRUCT() invocations live in Reflection.hpp, which is private (src/lib/).

Only .cpp files in src/lib/ include Reflection.hpp. And there are only four of them (not one, but a small number anyway :-)).

Yes, the requirements are met. My concern was only about compilation time. We can open an issue and just refer to the comment. We can investigate this later because it's not going to be that simple anyway.

… boilerplate This introduces Boost.Describe and Boost.Mp11 and applies them across metadata types (symbols, enums, inline elements) to replace hand-written io.map() calls with reflection-based code. This improves maintainability without altering the public API or user-facing features. Boost.Describe and Boost.Mp11 are *private* dependencies, i.e. they are not used in any public Mr. Docs include.

Reason: Avoiding timeouts in the Clang 21 + MSan tests.

pdimov reviewed Dec 9, 2025

View reviewed changes

include/mrdocs/Metadata/Symbol/EnumToString.hpp Outdated Show resolved Hide resolved

vinniefalco reviewed Dec 9, 2025

View reviewed changes

include/mrdocs/Metadata/DocComment/Inline/ImageInline.hpp Outdated Show resolved Hide resolved

vinniefalco reviewed Dec 9, 2025

View reviewed changes

include/mrdocs/Metadata/Symbol/Namespace.hpp Outdated Show resolved Hide resolved

gennaroprota force-pushed the develop branch 6 times, most recently from d8c7267 to f3274f4 Compare December 9, 2025 19:06

alandefreitas reviewed Dec 9, 2025

View reviewed changes

alandefreitas changed the title ~~refactor(metadata): integrate Boost.Describe to remove manual mapping boilerplate~~ refactor(metadata): integrate Boost.Describe Dec 9, 2025

gennaroprota force-pushed the develop branch from f3274f4 to d3c9cbd Compare December 10, 2025 09:58

gennaroprota marked this pull request as draft December 10, 2025 14:09

gennaroprota force-pushed the develop branch 2 times, most recently from 6bfe8ac to 394c55a Compare December 11, 2025 19:09

gennaroprota force-pushed the develop branch 2 times, most recently from adf50c8 to 7485284 Compare December 24, 2025 11:49

gennaroprota force-pushed the develop branch 9 times, most recently from ba65b54 to 45cde41 Compare January 5, 2026 16:24

gennaroprota force-pushed the develop branch 10 times, most recently from ef512c3 to f66b5b7 Compare January 7, 2026 11:16

gennaroprota marked this pull request as ready for review January 7, 2026 13:00

alandefreitas reviewed Jan 7, 2026

View reviewed changes

gennaroprota force-pushed the develop branch 4 times, most recently from 2de4d9d to dd3fb73 Compare January 12, 2026 17:13

gennaroprota force-pushed the develop branch 3 times, most recently from e5fe9a8 to cd9b8ca Compare January 16, 2026 16:41

gennaroprota added 2 commits January 16, 2026 18:23

ci: increase the ctest timeout to 9000

1425bdf

Reason: Avoiding timeouts in the Clang 21 + MSan tests.

gennaroprota force-pushed the develop branch from cd9b8ca to 1425bdf Compare January 16, 2026 17:23

refactor(metadata): integrate Boost.Describe #1130

Are you sure you want to change the base?

refactor(metadata): integrate Boost.Describe #1130

Conversation

gennaroprota commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Warnings

🧾 Changes by Scope

🔝 Top Files

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alandefreitas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alandefreitas commented Dec 10, 2025

Uh oh!

alandefreitas commented Dec 13, 2025

Uh oh!

codecov bot commented Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

cppalliance-bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alandefreitas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

gennaroprota commented Dec 9, 2025 •

edited

Loading

github-actions bot commented Dec 9, 2025 •

edited

Loading

codecov bot commented Dec 24, 2025 •

edited

Loading

cppalliance-bot commented Jan 7, 2026 •

edited

Loading