refactor: split base and derived classes

Split base and derived classes into their own headers to remove circular dependencies in the code.

Author: alandefreitas

CMakeLists.txt

@@ -321,7 +321,9 @@ target_include_directories(mrdocs-core
     "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>"
     PRIVATE
     "${PROJECT_SOURCE_DIR}/src"
-    "${PROJECT_BINARY_DIR}/src")
+    "${PROJECT_BINARY_DIR}/src"
+    "${PROJECT_SOURCE_DIR}/third-party/lua/src"
+)
 target_compile_definitions(
     mrdocs-core
     PUBLIC

docs/modules/ROOT/pages/contribute.adoc

@@ -46,6 +46,15 @@ Thus, after the command line and configuration file options are parsed, they are
 
 As a last step, `DoGenerateAction` converts the public `Config` settings into a `ConfigImpl` object, which is used by the rest of the program with the parsed options.
 
+[#representing_symbols]
+== Representing Symbols
+
+MrDocs has many categories of objects, where we utilize polymorphism with a fixed set of valid derived types, including Symbols (functions, classes, and enums), Javadoc blocks, template parameters, template arguments, and data types. For each such family, we follow a consistent file layout. Most of these families are defined in the `mrdocs/Metadata` directory.
+
+Each base class is defined in its own header and, when necessary, implementation file. Each derived class also has its own header and implementation file. Finally, there is a single aggregator header file that includes all the derived headers. This file centralizes logic that requires knowledge of the full set of variants, such as visitors, comparison operators, and other operations that depend on the discriminator.
+
+This pattern keeps the individual derived types self-contained while making cross-variant operations explicit and localized. When adding a new derived type, contributors should create its header and source file alongside the existing ones and update the corresponding aggregator file to register the new variant. This keeps the codebase predictable, avoids scattering logic, and ensures that operations over polymorphic families remain easy to find and maintain.
+
 [#extract_symbols]
 === Extracting Symbols
 
@@ -201,6 +210,8 @@ This directory contains build scripts and configuration files for third-party li
 ** `third-party/duktape/`—CMake scripts for Duktape
 ** `third-party/lua/`—A bundled Lua interpreter
 
+== Polymorphism
+
 == Coding Standards
 
 === Paths

include/mrdocs/ADT/Nullable.hpp

@@ -13,12 +13,11 @@
 #define MRDOCS_API_ADT_NULLABLE_HPP
 
 #include <mrdocs/Platform.hpp>
-
+#include <cmath>
+#include <concepts>
+#include <memory>
 #include <type_traits>
 #include <utility>
-#include <memory>
-#include <concepts>
-#include <cmath>
 
 namespace clang::mrdocs {
 
@@ -315,4 +314,4 @@ null_of() noexcept(noexcept(nullable_traits<T>::null()))
 
 } // clang::mrdocs
 
-#endif
+#endif // MRDOCS_API_ADT_NULLABLE_HPP

include/mrdocs/ADT/Polymorphic.hpp

@@ -12,9 +12,9 @@
 #ifndef MRDOCS_API_ADT_POLYMORPHIC_HPP
 #define MRDOCS_API_ADT_POLYMORPHIC_HPP
 
-#include <concepts>
-#include <mrdocs/Support/Assert.hpp>
 #include <mrdocs/ADT/Nullable.hpp>
+#include <mrdocs/Support/Assert.hpp>
+#include <concepts>
 #include <utility>
 
 namespace clang::mrdocs {
@@ -26,9 +26,7 @@ namespace clang::mrdocs {
 
     It implements a tweaked version of std::polymorphic, based on the
     reference implementation for P3019R14. Differences are:
-    * It supports nullability, which was originally supported in P3019 through
-      std::optional specializations, but was later removed from the paper.
-    * It implements comparison operators with a very project specific design.
+    * It implements comparison operators with a very project-specific design.
     * Fixed allocator, not parametrizable.
     * No initializer_list constructor.
 
@@ -37,13 +35,14 @@ namespace clang::mrdocs {
     To copy polymorphic objects, the class uses the
     copy constructor of the owned derived-type
     object when copying to another value.
-    Similarly, to allow correct destruction of
+    Similarly, to allow the correct destruction of
     derived objects, it uses the destructor of
     the owned derived-type object in the
     destructor.
 */
 template <class T>
 class Polymorphic {
+    // Base class for type-erasure.
     struct WrapperBase {
         virtual constexpr ~WrapperBase() = default;
         virtual T& getValue() = 0;
@@ -61,7 +60,8 @@ class Polymorphic {
         constexpr WrapperBase* clone() override { return new Wrapper(Value); }
     };
 
-    WrapperBase* WB; // nullptr only when constructed/reset by nullable_traits
+    // nullptr only when constructed/reset by nullable_traits
+    WrapperBase* WB = nullptr;
 
     // Private null token and constructor: only the friend traits can call this.
     struct _null_t { explicit constexpr _null_t(int) {} };
@@ -70,15 +70,15 @@ class Polymorphic {
     // Allow the traits specialization to access private members/ctors.
     friend struct nullable_traits<Polymorphic<T>>;
 
-// std::polymorphic has a default constructor that
-// default-constructs the base type T if it's default-constructible.
-// We disable this constructor because this is always an error
-// in MrDocs.
-//    constexpr explicit Polymorphic()
-//    requires std::is_default_constructible_v<T>
-//             && std::is_copy_constructible_v<T>
-//        : WB(new Wrapper<T>())
-//    {}
+    // std::polymorphic has a default constructor that
+    // default-constructs the base type T if it's default-constructible.
+    // We disable this constructor because this is always an error
+    // in MrDocs.
+    // constexpr explicit Polymorphic()
+    // requires std::is_default_constructible_v<T>
+    //          && std::is_copy_constructible_v<T>
+    //     : WB(new Wrapper<T>())
+    // {}
 
 public:
     using value_type = T;
@@ -96,7 +96,10 @@ class Polymorphic {
                  std::derived_from<std::remove_cvref_t<U>, T>
         : WB(new Wrapper<std::remove_cvref_t<U>>(std::forward<U>(u))) {}
 
-    /** In-place constructor for a specific derived U. */
+    /** In-place constructor for a specific derived U.
+
+        @param ts Arguments to forward to U's constructor.
+     */
     template <class U, class... Ts>
     explicit constexpr Polymorphic(std::in_place_type_t<U>, Ts&&... ts)
         requires std::same_as<std::remove_cvref_t<U>, U> &&
@@ -288,4 +291,4 @@ struct nullable_traits<Polymorphic<T>>
 
 } // namespace clang::mrdocs
 
-#endif
+#endif // MRDOCS_API_ADT_POLYMORPHIC_HPP

include/mrdocs/ADT/UnorderedStringMap.hpp

@@ -12,8 +12,8 @@
 #ifndef MRDOCS_API_ADT_UNORDEREDSTRINGMAP_HPP
 #define MRDOCS_API_ADT_UNORDEREDSTRINGMAP_HPP
 
-#include <unordered_map>
 #include <string>
+#include <unordered_map>
 
 namespace clang::mrdocs {
 
@@ -34,4 +34,4 @@ using UnorderedStringMultiMap = std::unordered_multimap<std::string, T, StringHa
 
 } // clang::mrdocs
 
-#endif
+#endif // MRDOCS_API_ADT_UNORDEREDSTRINGMAP_HPP

include/mrdocs/Config.hpp

@@ -13,9 +13,9 @@
 #define MRDOCS_API_CONFIG_HPP
 
 #include <mrdocs/Platform.hpp>
-#include <mrdocs/Support/Error.hpp>
 #include <mrdocs/Dom/Object.hpp>
 #include <mrdocs/PublicSettings.hpp>
+#include <mrdocs/Support/Error.hpp>
 #include <functional>
 #include <memory>
 #include <string>
@@ -225,4 +225,4 @@ class MRDOCS_DECL
 } // mrdocs
 } // clang
 
-#endif
+#endif // MRDOCS_API_CONFIG_HPP

include/mrdocs/Config/ReferenceDirectories.hpp

@@ -9,8 +9,8 @@
 // Official repository: https://github.com/cppalliance/mrdocs
 //
 
-#ifndef MRDOCS_API_CONFIG_REFERENCE_DIRECTORIES_HPP
-#define MRDOCS_API_CONFIG_REFERENCE_DIRECTORIES_HPP
+#ifndef MRDOCS_API_CONFIG_REFERENCEDIRECTORIES_HPP
+#define MRDOCS_API_CONFIG_REFERENCEDIRECTORIES_HPP
 
 #include <string>
 
@@ -34,4 +34,4 @@ struct ReferenceDirectories
 } // mrdocs
 } // clang
 
-#endif
+#endif // MRDOCS_API_CONFIG_REFERENCEDIRECTORIES_HPP

include/mrdocs/Corpus.hpp

@@ -17,11 +17,11 @@
 #include <mrdocs/Platform.hpp>
 #include <mrdocs/Config.hpp>
 #include <mrdocs/Metadata.hpp>
+#include <algorithm>
 #include <string>
 #include <type_traits>
 #include <utility>
 #include <vector>
-#include <algorithm>
 
 namespace clang::mrdocs {
 
@@ -500,4 +500,4 @@ getParents(Corpus const& C, Info const& I);
 
 } // clang::mrdocs
 
-#endif
+#endif // MRDOCS_API_CORPUS_HPP

include/mrdocs/Dom.hpp

@@ -13,4 +13,4 @@
 
 #include <mrdocs/Dom/Value.hpp>
 
-#endif
+#endif // MRDOCS_API_DOM_HPP

include/mrdocs/Dom/LazyArray.hpp

@@ -8,11 +8,11 @@
 // Official repository: https://github.com/cppalliance/mrdocs
 //
 
-#ifndef MRDOCS_LIB_DOM_LAZY_ARRAY_HPP
-#define MRDOCS_LIB_DOM_LAZY_ARRAY_HPP
+#ifndef MRDOCS_API_DOM_LAZYARRAY_HPP
+#define MRDOCS_API_DOM_LAZYARRAY_HPP
 
-#include <mrdocs/Dom.hpp>
 #include <mrdocs/Platform.hpp>
+#include <mrdocs/Dom.hpp>
 #include <mrdocs/Support/Error.hpp>
 #include <ranges>
 #include <string_view>
@@ -195,4 +195,4 @@ TransformArray(T const& arr, F const& f)
 } // mrdocs
 } // clang
 
-#endif
+#endif // MRDOCS_API_DOM_LAZYARRAY_HPP