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 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).

Warning

Source changed but no tests or fixtures were updated. Add coverage or label with no-tests-needed / [skip danger tests] when appropriate.

✨ Highlights

None noted.

🧾 Changes by Scope

Scope	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
Source	887	592	295	49	2	47	-	-
CI / Roadmap	50	50	-	1	-	1	-	-
Third-party	28	28	-	2	2	-	-	-
Build / Toolchain	18	18	-	1	-	1	-	-
Docs	8	8	-	1	-	1	-	-
Total	991	696	295	54	4	50	-	-

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

🔝 Top Files

include/mrdocs/Metadata/Symbol/SymbolDescribeMapper.hpp (Source): 174 lines Δ (+174 / -0)
include/mrdocs/Metadata/Symbol/Function.hpp (Source): 75 lines Δ (+34 / -41)
include/mrdocs/Metadata/Symbol/EnumToString.hpp (Source): 52 lines Δ (+52 / -0)

Generated by 🚫 dangerJS against 14342ee

include/mrdocs/Metadata/Symbol/EnumToString.hpp

vinniefalco · 2025-12-09T13:33:41Z

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

 #ifndef MRDOCS_API_METADATA_DOCCOMMENT_INLINE_IMAGEINLINE_HPP
 #define MRDOCS_API_METADATA_DOCCOMMENT_INLINE_IMAGEINLINE_HPP

+#include <boost/describe/class.hpp>


includes should be ordered from most specific to most general. describe is general. std includes are most general

include/mrdocs/Metadata/Symbol/Namespace.hpp

alandefreitas

Great job! 👏😀🎉

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

.github/workflows/ci.yml

+        uses: alandefreitas/cpp-actions/[email protected]
+        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?

alandefreitas · 2025-12-09T18:54:06Z

CMakeLists.txt

 string(REGEX REPLACE " /W[0-4]" "" CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}")

+# Boost.Describe + Boost.Mp11 (header-only, fetched via bootstrap.py recipes)
+set(BOOST_DESCRIBE_ROOT "${CMAKE_SOURCE_DIR}/build/third-party/source/boost_describe")


Hard-coded paths are a no-no. 😅 You can write a patch for each that installs and exports them as Boost::describe and Boost::mp11. This way, you still don't depend on the Boost root project. Also, I thought there would be dependency on Boost::config here.

include/mrdocs/Metadata/Expression.hpp

include/mrdocs/Metadata/Symbol/EnumToString.hpp

include/mrdocs/Metadata/Symbol/Namespace.hpp

alandefreitas · 2025-12-09T19:08:41Z

include/mrdocs/Metadata/Symbol/NamespaceAlias.hpp

 {
    tag_invoke(t, io, I.asInfo(), domCorpus);
-    io.map("aliasedSymbol", I.AliasedSymbol);
+    mapWithDescribe(io, I, domCorpus);


Can't mapWithDescribe just iterate the base classes itself?

Should it always iterate all bases? I was afraid there was some special case somewhere for which only one base was mapped. If you confirm I can iterate all bases, always, I'll do that :-).

After writing the above comment, I found this:

struct ImageInline final : InlineCommonBase<InlineKind::Image> , InlineContainer { /** Image source URL or path. */ std::string src; /** Alternate text when the image cannot be shown. */ std::string alt; /** Order images by source, alt text, and inline children. */ auto operator<=>(ImageInline const&) const = default; /** Equality compares source, alt text, and contents. */ bool operator==(ImageInline const&) const noexcept = default; }; template <class IO> void tag_invoke( dom::LazyObjectMapTag t, IO& io, ImageInline const& I, DomCorpus const* domCorpus) { tag_invoke(t, io, dynamic_cast<Inline const&>(I), domCorpus); tag_invoke(t, io, dynamic_cast<InlineContainer const&>(I), domCorpus); mapWithDescribe(io, I, domCorpus); }

alandefreitas · 2025-12-09T19:11:46Z

include/mrdocs/Metadata/Symbol/SymbolDescribeMapper.hpp

+
+namespace detail {
+
+/** Helper to determine if a member should be mapped based on its value.


Can't we have all the Boost.Describe related stuff in a single header? And will these headers always be public? But that would make mp11 and describe the first public dependencies of mrdocs, and cmakelists.txt and mrdocs.yml would need to be adapted accordingly.

What do you mean by "all the Boost.Describe related stuff"?

Authors of plugins don't need the Describe data (or do they) so it would be nice not to require plugins to have Boost installed.

What do you mean by "all the Boost.Describe related stuff"?

That there should be no #include <boost/whatever.hpp> in public files.

or do they

The members are already "described" for extensions. Authors of plugins are probably going to iterate the members of objects often, but this can be abstracted without exposing boost.

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.

… 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.

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.

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/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 from c269600 to 0cd3a50 Compare December 10, 2025 17:15

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

gennaroprota added 4 commits December 12, 2025 11:13

fix: really exclude symbols defined by Boost.Describe

33ed1ad

fix: fix

86f39bd

fix: Releases CI steps

4699061

fix: also clone Boost.Describe and Boost.Mp11 in the CI release steps

14342ee


		namespace detail {

		/** Helper to determine if a member should be mapped based on its value.

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

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

✨ Highlights

🧾 Changes by Scope

🔝 Top Files

Uh oh!

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alandefreitas commented Dec 10, 2025

Uh oh!

alandefreitas commented Dec 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Dec 9, 2025 •

edited

Loading

gennaroprota Dec 10, 2025 •

edited

Loading