refactor(metadata): integrate Boost.Describe to remove manual mapping 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.

Author: gennaroprota

.github/workflows/ci.yml

@@ -432,6 +432,36 @@ jobs:
         run: |
           rm -r ../third-party/llvm-project
 
+      - name: Install Boost.Describe
+        uses: alandefreitas/cpp-actions/[email protected]
+        with:
+          source-dir: ../build/third-party/source/boost_describe
+          git-repository: https://github.com/boostorg/describe
+          git-tag: boost-1.89.0
+          build-dir: ${sourceDir}/build
+          cc: ${{ steps.setup-cpp.outputs.cc }}
+          cxx: ${{ steps.setup-cpp.outputs.cxx }}
+          build-type: Release
+          shared: false
+          install: false
+          run-tests: false
+          trace-commands: true
+
+      - name: Install Boost.Mp11
+        uses: alandefreitas/cpp-actions/[email protected]
+        with:
+          source-dir: ..build/third-party/source/boost_mp11
+          git-repository: https://github.com/boostorg/mp11
+          git-tag: boost-1.89.0
+          build-dir: ${sourceDir}/build
+          cc: ${{ steps.setup-cpp.outputs.cc }}
+          cxx: ${{ steps.setup-cpp.outputs.cxx }}
+          build-type: Release
+          shared: false
+          install: false
+          run-tests: false
+          trace-commands: true
+
       - name: Install Duktape
         uses: alandefreitas/cpp-actions/[email protected]
         with:

CMakeLists.txt

@@ -277,6 +277,20 @@ llvm_map_components_to_libnames(llvm_libs all)
 string(REGEX REPLACE " /W[0-4]" "" CMAKE_C_FLAGS "${CMAKE_C_FLAGS}")
 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")
+set(BOOST_MP11_ROOT     "${CMAKE_SOURCE_DIR}/build/third-party/source/boost_mp11")
+
+add_library(boost_mp11 INTERFACE)
+target_include_directories(boost_mp11 INTERFACE "${BOOST_MP11_ROOT}/include")
+
+add_library(boost_describe INTERFACE)
+target_include_directories(boost_describe INTERFACE "${BOOST_DESCRIBE_ROOT}/include")
+target_link_libraries(boost_describe INTERFACE boost_mp11)
+set_target_properties(boost_describe boost_mp11 PROPERTIES
+    EXPORT_NAME ""
+)
+
 # Duktape
 find_package(duktape CONFIG)
 if (NOT DUKTAPE_FOUND)
@@ -322,6 +336,8 @@ target_include_directories(mrdocs-core
     PUBLIC
     "$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include/>"
     "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include/>"
+    "$<BUILD_INTERFACE:${BOOST_DESCRIBE_ROOT}/include>"
+    "$<BUILD_INTERFACE:${BOOST_MP11_ROOT}/include>"
     "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>"
     PRIVATE
     "${PROJECT_SOURCE_DIR}/src"

include/mrdocs/Dom/LazyArray.hpp

@@ -4,6 +4,7 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2024 Alan de Freitas ([email protected])
+// Copyright (c) 2025 Gennaro Prota ([email protected])
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
@@ -211,6 +212,26 @@ TransformArray(T const& arr, F const& f)
 }
 
 } // dom
+
+class DomCorpus;
+
+/** Map a vector of strings to a @ref dom::Value object.
+
+    @param v The output parameter to receive the dom::Value.
+    @param elems The vector of T's to convert.
+    @param domCorpus The DomCorpus used to resolve references.
+ */
+template <typename T>
+void
+tag_invoke(
+    dom::ValueFromTag,
+    dom::Value& v,
+    std::vector<T> const& elems,
+    DomCorpus const* domCorpus)
+{
+    v = dom::LazyArray(elems, domCorpus);
+}
+
 } // mrdocs
 
 

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

@@ -5,16 +5,19 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2025 Alan de Freitas ([email protected])
+// Copyright (c) 2025 Gennaro Prota ([email protected])
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
 
 #ifndef MRDOCS_API_METADATA_DOCCOMMENT_INLINE_IMAGEINLINE_HPP
 #define MRDOCS_API_METADATA_DOCCOMMENT_INLINE_IMAGEINLINE_HPP
 
+#include <boost/describe/class.hpp>
 #include <mrdocs/Platform.hpp>
 #include <mrdocs/ADT/Polymorphic.hpp>
 #include <mrdocs/Metadata/DocComment/Inline/TextInline.hpp>
+#include <mrdocs/Metadata/Symbol/SymbolDescribeMapper.hpp>
 #include <string>
 
 namespace mrdocs::doc {
@@ -52,6 +55,12 @@ struct ImageInline final
     bool operator==(ImageInline const&) const noexcept = default;
 };
 
+BOOST_DESCRIBE_STRUCT(
+    ImageInline,
+    (InlineCommonBase<InlineKind::Image>, InlineContainer),
+    (src, alt)
+)
+
 /** Map the @ref ImageInline to a @ref dom::Object.
 
     @param t The tag.
@@ -69,8 +78,7 @@ tag_invoke(
 {
     tag_invoke(t, io, dynamic_cast<Inline const&>(I), domCorpus);
     tag_invoke(t, io, dynamic_cast<InlineContainer const&>(I), domCorpus);
-    io.map("src", I.src);
-    io.map("alt", I.alt);
+    mapWithDescribe(io, I, domCorpus);
 }
 
 /** Return the @ref ImageInline as a @ref dom::Value object.

include/mrdocs/Metadata/Expression.hpp

@@ -4,6 +4,7 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2023 Krystian Stasiowski ([email protected])
+// Copyright (c) 2025 Gennaro Prota ([email protected])
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
@@ -13,12 +14,17 @@
 
 #include <mrdocs/Platform.hpp>
 #include <mrdocs/ADT/Optional.hpp>
+#include <mrdocs/Dom/Array.hpp>
+#include <mrdocs/Dom/LazyObject.hpp>
+#include <mrdocs/Dom/Value.hpp>
 #include <concepts>
 #include <optional>
 #include <string>
 
 namespace mrdocs {
 
+class DomCorpus;
+
 /** Represents an expression
 */
 struct ExprInfo
@@ -90,6 +96,39 @@ static void merge(
     }
 }
 
+/** Map an ExprInfo to a @ref dom::Value object.
+
+    @param v The output parameter to receive the dom::Value.
+    @param expr The expression info to convert.
+*/
+inline
+void
+tag_invoke(
+    dom::ValueFromTag,
+    dom::Value& v,
+    ExprInfo const& expr,
+    DomCorpus const*)
+{
+    v = expr.Written;
+}
+
+/** Map an ExprInfo to a @ref dom::Value object.
+
+    @param v The output parameter to receive the dom::Value.
+    @param expr The expression info to convert.
+*/
+inline
+void
+tag_invoke(
+    dom::LazyObjectMapTag,
+    dom::Value& v,
+    ExprInfo const& expr,
+    DomCorpus const*
+)
+{
+    v = expr.Written;
+}
+
 } // mrdocs
 
 #endif

include/mrdocs/Metadata/Symbol/Concept.hpp

@@ -4,19 +4,22 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2024 Krystian Stasiowski ([email protected])
+// Copyright (c) 2025 Gennaro Prota ([email protected])
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
 
 #ifndef MRDOCS_API_METADATA_SYMBOL_CONCEPT_HPP
 #define MRDOCS_API_METADATA_SYMBOL_CONCEPT_HPP
 
+#include <boost/describe/class.hpp>
 #include <mrdocs/Platform.hpp>
 #include <mrdocs/ADT/Optional.hpp>
 #include <mrdocs/ADT/Polymorphic.hpp>
 #include <mrdocs/Metadata/Expression.hpp>
 #include <mrdocs/Metadata/Symbol.hpp>
 #include <mrdocs/Metadata/Symbol/Source.hpp>
+#include <mrdocs/Metadata/Symbol/SymbolDescribeMapper.hpp>
 #include <mrdocs/Metadata/Template.hpp>
 
 namespace mrdocs {
@@ -49,6 +52,12 @@ struct ConceptSymbol final
     operator<=>(ConceptSymbol const& other) const;
 };
 
+BOOST_DESCRIBE_STRUCT(
+    ConceptSymbol,
+    (SymbolCommonBase<SymbolKind::Concept>),
+    (Template, Constraint)
+)
+
 /** Merge another ConceptSymbol into this one.
 */
 MRDOCS_DECL
@@ -71,11 +80,8 @@ tag_invoke(
     DomCorpus const* domCorpus)
 {
     tag_invoke(t, io, I.asInfo(), domCorpus);
-    io.map("template", I.Template);
-    if (!I.Constraint.Written.empty())
-    {
-        io.map("constraint", I.Constraint.Written);
-    }
+    mapWithDescribe(io, I, domCorpus);
+
 }
 
 /** Map the ConceptSymbol to a @ref dom::Value object.

include/mrdocs/Metadata/Symbol/Enum.hpp

@@ -5,18 +5,21 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2023 Vinnie Falco ([email protected])
+// Copyright (c) 2025 Gennaro Prota ([email protected])
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
 
 #ifndef MRDOCS_API_METADATA_SYMBOL_ENUM_HPP
 #define MRDOCS_API_METADATA_SYMBOL_ENUM_HPP
 
+#include <boost/describe/class.hpp>
 #include <mrdocs/Platform.hpp>
 #include <mrdocs/ADT/Polymorphic.hpp>
 #include <mrdocs/Dom/LazyArray.hpp>
 #include <mrdocs/Metadata/Symbol.hpp>
 #include <mrdocs/Metadata/Symbol/Source.hpp>
+#include <mrdocs/Metadata/Symbol/SymbolDescribeMapper.hpp>
 #include <mrdocs/Metadata/Type.hpp>
 
 namespace mrdocs {
@@ -65,6 +68,12 @@ struct EnumSymbol final
     }
 };
 
+BOOST_DESCRIBE_STRUCT(
+    EnumSymbol,
+    (SymbolCommonBase<SymbolKind::Enum>),
+    (Scoped, UnderlyingType, Constants)
+)
+
 /** Return the list of enum constants for this symbol.
 */
 inline

include/mrdocs/Metadata/Symbol/EnumConstant.hpp

@@ -4,15 +4,18 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2023 Krystian Stasiowski ([email protected])
+// Copyright (c) 2025 Gennaro Prota ([email protected])
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
 
 #ifndef MRDOCS_API_METADATA_SYMBOL_ENUMCONSTANT_HPP
 #define MRDOCS_API_METADATA_SYMBOL_ENUMCONSTANT_HPP
 
+#include <boost/describe/class.hpp>
 #include <mrdocs/Metadata/Expression.hpp>
 #include <mrdocs/Metadata/Symbol.hpp>
+#include <mrdocs/Metadata/Symbol/SymbolDescribeMapper.hpp>
 #include <mrdocs/Metadata/Symbol/Source.hpp>
 
 namespace mrdocs {
@@ -36,6 +39,12 @@ struct EnumConstantSymbol final
     }
 };
 
+BOOST_DESCRIBE_STRUCT(
+    EnumConstantSymbol,
+    (SymbolCommonBase<SymbolKind::EnumConstant>),
+    (Initializer)
+)
+
 /** Merge another EnumConstantSymbol into this one.
     @param I Destination symbol to update.
     @param Other Source symbol providing data.
@@ -60,10 +69,7 @@ tag_invoke(
     DomCorpus const* domCorpus)
 {
     tag_invoke(t, io, I.asInfo(), domCorpus);
-    if (!I.Initializer.Written.empty())
-    {
-        io.map("initializer", I.Initializer.Written);
-    }
+    mapWithDescribe(io, I, domCorpus);
 }
 
 /** Map the EnumConstantSymbol to a @ref dom::Value object.

include/mrdocs/Metadata/Symbol/EnumToString.hpp

@@ -0,0 +1,52 @@
+//
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2025 Gennaro Prota ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#ifndef MRDOCS_METADATA_SYMBOL_ENUMTOSTRING_HPP
+#define MRDOCS_METADATA_SYMBOL_ENUMTOSTRING_HPP
+
+#include <boost/describe/enumerators.hpp>
+#include <boost/mp11.hpp>
+#include <mrdocs/Support/Assert.hpp>
+#include <mrdocs/Support/String.hpp>
+#include <string>
+#include <type_traits>
+
+namespace mrdocs {
+
+/** Convert a Boost.Describe'd enumerator to string form.
+*/
+template <typename Enum>
+    requires std::is_enum_v<Enum>
+std::string
+toString(Enum e) noexcept
+{
+    std::string result;
+    boost::mp11::mp_for_each<
+        boost::describe::describe_enumerators<Enum>>(
+        [&](auto const& D)
+        {
+            using Descriptor = std::decay_t<decltype(D)>;
+            if (Descriptor::value == e)
+            {
+                result = toKebabCase(Descriptor::name);
+            }
+        });
+
+    if (!result.empty())
+    {
+        return result;
+    }
+
+    MRDOCS_UNREACHABLE();
+}
+
+}
+
+#endif