refactor(metadata): integrate Boost.Describe

.github/workflows/ci.yml

@@ -432,6 +432,38 @@ 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: true
+          install-prefix: ${sourceDir}/install
+          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: true
+          install-prefix: ${sourceDir}/install
+          run-tests: false
+          trace-commands: true
+
       - name: Install Duktape
         uses: alandefreitas/cpp-actions/[email protected]
         with:
@@ -804,6 +836,24 @@ jobs:
           modules-exclude-paths: ''
           trace-commands: true
 
+      - name: Clone Boost.Describe
+        uses: alandefreitas/cpp-actions/[email protected]
+        id: boost-describe-clone
+        with:
+          branch: develop
+          modules: describe
+          boost-dir: boost
+          trace-commands: true
+
+      - name: Clone Boost.Mp11
+        uses: alandefreitas/cpp-actions/[email protected]
+        id: boost-mp11-clone
+        with:
+          branch: develop
+          modules: mp11
+          boost-dir: boost
+          trace-commands: true
+
       - name: Set up llvm-symbolizer
         if: ${{ runner.os != 'Windows' }}
         run: |

CMakeLists.txt

@@ -171,6 +171,20 @@ else()
     )
 endif()
 
+# 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 ""
+)
+
 #-------------------------------------------------
 #
 # Docs build
@@ -208,6 +222,8 @@ if (MRDOCS_DOCUMENTATION_BUILD)
             "${BIN_INCLUDE_DIR}"
     )
 
+    target_link_libraries(mrdocs-documentation-build PRIVATE boost_describe boost_mp11)
+
     # Other defines so headers compile standalone
     target_compile_definitions(mrdocs-documentation-build PRIVATE MRDOCS_STATIC_LINK)
 
@@ -322,6 +338,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"

docs/mrdocs.yml

@@ -13,6 +13,14 @@ implementation-defined:
   - 'mrdocs::detail'
   - 'mrdocs::report::detail'
   - 'mrdocs::dom::detail'
+exclude-symbols:
+    # Symbols defined when using the Boost.Describe macros.
+  - '**::boost_base_descriptor_fn'
+  - '**::boost_public_member_descriptor_fn'
+  - '**::boost_protected_member_descriptor_fn'
+  - '**::boost_private_member_descriptor_fn'
+  - '**::boost_enum_descriptor_fn'
+  - '**::should_use_BOOST_DESCRIBE_NESTED_ENUM'
 multipage: true
 generator: adoc
 cmake: '-D MRDOCS_DOCUMENTATION_BUILD=ON'

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.