docs: mrdocs self-reference doc comments

Author: alandefreitas

docs/config-headers/include/mrdocs/PublicSettings.hpp

@@ -466,6 +466,44 @@ struct PublicSettings {
      */
     std::vector<SymbolGlobPattern> implementationDefined;
 
+    //--------------------------------------------
+    // Semantic Parsing
+    // 
+    // Options to control how the source code is parsed
+    //--------------------------------------------
+
+    /** Include path prefixes allowed to be missing
+    
+        Specifies path prefixes for include files that, if missing, will not
+        cause documentation generation to fail.
+        
+        Missing files with these prefixes are served as empty files from an
+        in-memory file system, allowing processing to continue.
+        
+        For example, use "llvm/" to forgive all includes from LLVM.
+        
+        If any such path is specified, MrDocs will attempt to synthesize
+        missing included types.
+        
+        Only simple sets of non-conflicting inferred types can be synthesized.
+        
+        For more complex types or for better control, provide a shim using the
+        "missing-include-shims" option.
+     */
+    std::vector<std::string> missingIncludePrefixes;
+
+    /** Shims for forgiven missing include files
+    
+        Specifies a map of include file paths to shim contents.
+        
+        If a missing include file matches a forgiven prefix, MrDocs will use
+        the shim content from this map as the file contents.
+        
+        If no shim is provided for a forgiven file, an empty file is used by
+        default.
+     */
+    std::map<std::string, std::string> missingIncludeShims;
+
     //--------------------------------------------
     // Comment Parsing
     // 
@@ -1064,17 +1102,18 @@ struct PublicSettings {
     /** Option Type
       */
     enum class OptionType {
-        ListPathGlob,
-        Unsigned,
+        Enum,
+        Path,
+        ListSymbolGlob,
         ListPath,
-        ListString,
-        Bool,
+        String,
+        Unsigned,
         FilePath,
+        ListPathGlob,
         DirPath,
-        Path,
-        Enum,
-        String,
-        ListSymbolGlob,
+        ListString,
+        Bool,
+        MapStringString,
     };
 
     /** Option validation traits
@@ -1091,16 +1130,17 @@ struct PublicSettings {
         std::optional<std::map<std::string, std::string>> filenameMapping = std::nullopt;
         std::variant<
             std::monostate,
-            unsigned,
+            LogLevel,
+            BaseMemberInheritance,
             std::vector<PathGlobPattern>,
-            std::vector<SymbolGlobPattern>,
+            unsigned,
+            Generator,
+            std::map<std::string, std::string>,
             SortSymbolBy,
+            std::vector<std::string>,
             bool,
-            LogLevel,
-            std::string,
-            Generator,
-            BaseMemberInheritance,
-            std::vector<std::string>> defaultValue = std::monostate();
+            std::vector<SymbolGlobPattern>,
+            std::string> defaultValue = std::monostate();
         std::string relativeTo = {};
         std::optional<std::string> deprecated = std::nullopt;
     };
@@ -1226,6 +1266,16 @@ struct PublicSettings {
             .type = OptionType::ListSymbolGlob,
             .required = false,
         }));
+        // Include path prefixes allowed to be missing
+        MRDOCS_TRY(std::forward<F>(f)(*this, "missing-include-prefixes", missingIncludePrefixes, dirs, OptionProperties{
+            .type = OptionType::ListString,
+            .required = false,
+        }));
+        // Shims for forgiven missing include files
+        MRDOCS_TRY(std::forward<F>(f)(*this, "missing-include-shims", missingIncludeShims, dirs, OptionProperties{
+            .type = OptionType::MapStringString,
+            .required = false,
+        }));
         // Use the first line of the comment as the brief
         MRDOCS_TRY(std::forward<F>(f)(*this, "auto-brief", autoBrief, dirs, OptionProperties{
             .type = OptionType::Bool,
@@ -1575,6 +1625,8 @@ struct PublicSettings {
     }
 
     /** Visit all options
+        
+        @param f The visitor
      */
     template <class F>
     void
@@ -1594,6 +1646,8 @@ struct PublicSettings {
         std::forward<F>(f)("exclude-symbols", excludeSymbols);
         std::forward<F>(f)("see-below", seeBelow);
         std::forward<F>(f)("implementation-defined", implementationDefined);
+        std::forward<F>(f)("missing-include-prefixes", missingIncludePrefixes);
+        std::forward<F>(f)("missing-include-shims", missingIncludeShims);
         std::forward<F>(f)("auto-brief", autoBrief);
         std::forward<F>(f)("auto-relates", autoRelates);
         std::forward<F>(f)("auto-function-metadata", autoFunctionMetadata);
@@ -1652,6 +1706,8 @@ struct PublicSettings {
     }
 
     /** Visit all options
+        
+        @param f The visitor
      */
     template <class F>
     void
@@ -1671,6 +1727,8 @@ struct PublicSettings {
         std::forward<F>(f)("exclude-symbols", excludeSymbols);
         std::forward<F>(f)("see-below", seeBelow);
         std::forward<F>(f)("implementation-defined", implementationDefined);
+        std::forward<F>(f)("missing-include-prefixes", missingIncludePrefixes);
+        std::forward<F>(f)("missing-include-shims", missingIncludeShims);
         std::forward<F>(f)("auto-brief", autoBrief);
         std::forward<F>(f)("auto-relates", autoRelates);
         std::forward<F>(f)("auto-function-metadata", autoFunctionMetadata);

docs/config-headers/src/tool/PublicToolArgs.hpp

@@ -48,6 +48,13 @@ struct PublicToolArgs {
      */
     llvm::cl::OptionCategory filtersCat;
 
+    /** Options to control how the source code is parsed
+
+        Mr.Docs uses libclang to parse the source code and extract symbols. The
+        following options control how the source code is parsed.
+     */
+    llvm::cl::OptionCategory semanticParsingCat;
+
     /** Options to control how comments are parsed
 
         Mr.Docs extracts metadata from the comments in the source code. The
@@ -315,6 +322,44 @@ struct PublicToolArgs {
      */
     llvm::cl::list<std::string> implementationDefined;
 
+    //--------------------------------------------
+    // Semantic Parsing
+    // 
+    // Options to control how the source code is parsed
+    //--------------------------------------------
+
+    /** Include path prefixes allowed to be missing
+    
+        Specifies path prefixes for include files that, if missing, will not
+        cause documentation generation to fail.
+        
+        Missing files with these prefixes are served as empty files from an
+        in-memory file system, allowing processing to continue.
+        
+        For example, use "llvm/" to forgive all includes from LLVM.
+        
+        If any such path is specified, MrDocs will attempt to synthesize
+        missing included types.
+        
+        Only simple sets of non-conflicting inferred types can be synthesized.
+        
+        For more complex types or for better control, provide a shim using the
+        "missing-include-shims" option.
+     */
+    llvm::cl::list<std::string> missingIncludePrefixes;
+
+    /** Shims for forgiven missing include files
+    
+        Specifies a map of include file paths to shim contents.
+        
+        If a missing include file matches a forgiven prefix, MrDocs will use
+        the shim content from this map as the file contents.
+        
+        If no shim is provided for a forgiven file, an empty file is used by
+        default.
+     */
+    llvm::cl::list<std::string> missingIncludeShims;
+
     //--------------------------------------------
     // Comment Parsing
     // 
@@ -912,6 +957,8 @@ struct PublicToolArgs {
         std::forward<F>(f)("exclude-symbols", excludeSymbols);
         std::forward<F>(f)("see-below", seeBelow);
         std::forward<F>(f)("implementation-defined", implementationDefined);
+        std::forward<F>(f)("missing-include-prefixes", missingIncludePrefixes);
+        std::forward<F>(f)("missing-include-shims", missingIncludeShims);
         std::forward<F>(f)("auto-brief", autoBrief);
         std::forward<F>(f)("auto-relates", autoRelates);
         std::forward<F>(f)("auto-function-metadata", autoFunctionMetadata);

docs/mrdocs.yml

@@ -15,6 +15,8 @@ include-symbols:
   - 'clang::mrdocs::**'
 implementation-defined:
   - 'clang::mrdocs::detail'
+  - 'clang::mrdocs::report::detail'
+  - 'clang::mrdocs::dom::detail'
 multipage: true
 generator: adoc
 cmake: '-D MRDOCS_DOCUMENTATION_BUILD=ON'

include/mrdocs/ADT/Polymorphic.hpp

@@ -77,15 +77,19 @@ template <class T> class Polymorphic {
   /// Default constructs the value type.
   explicit constexpr Polymorphic() : Polymorphic(std::in_place_type<T>) {}
 
-  /// Forwarding constructor.
+  /** Forwarding constructor.
+   * @param u The object to copy.
+   */
   template <class U>
   constexpr explicit Polymorphic(U &&u)
     requires(not std::same_as<Polymorphic, std::remove_cvref_t<U>>) &&
             std::copy_constructible<std::remove_cvref_t<U>> &&
             std::derived_from<std::remove_cvref_t<U>, T>
       : WB(new Wrapper<std::remove_cvref_t<U>>(std::forward<U>(u))) {}
 
-  /// In place constructor.
+  /** In place constructor
+   * @param ts Arguments to forward to the constructor of U.
+   */
   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> &&
@@ -171,7 +175,7 @@ template <class T> inline constexpr bool IsPolymorphic<Polymorphic<T>> = true;
 
 } // namespace detail
 
-/** Compares two polymorphic objects that have visit functions
+/** @brief Compares two polymorphic objects that have visit functions
 
     This function compares two Polymorphic objects that
     have visit functions for the Base type.
@@ -209,7 +213,7 @@ CompareDerived(
             : std::strong_ordering::greater;
 }
 
-/// @copydoc CompareDerived
+/// @copydoc CompareDerived(Polymorphic<Base> const&, Polymorphic<Base> const&)
 template <class Base>
   requires(!detail::IsPolymorphic<Base>) && detail::CanVisitCompare<Base>
 auto CompareDerived(Base const &lhs, Base const &rhs) {

include/mrdocs/Config.hpp

@@ -16,7 +16,6 @@
 #include <mrdocs/Support/Error.hpp>
 #include <mrdocs/Dom/Object.hpp>
 #include <mrdocs/PublicSettings.hpp>
-#include "lib/Support/YamlFwd.hpp"
 #include <functional>
 #include <memory>
 #include <string>
@@ -25,6 +24,13 @@
 #include <utility>
 #include <vector>
 
+namespace llvm::yaml {
+
+template<class T>
+struct MappingTraits;
+
+} // llvm::yaml
+
 namespace clang {
 namespace mrdocs {
 
@@ -62,13 +68,13 @@ class MRDOCS_DECL
      */
     struct Settings : public PublicSettings
     {
-        /**
-         * @brief Loads the public configuration settings from the specified YAML file.
+        /** @brief Loads the public configuration settings from the specified YAML file.
          *
          * This function takes a YAML file and a set of reference directories as input.
          * It parses the YAML file and loads the configuration settings into a Config::Settings object.
          * The reference directories are used to resolve any relative paths in the configuration settings.
          *
+         * @param s A reference to a Config::Settings object where the configuration settings will be loaded.
          * @param configYaml A string view representing the YAML file containing the configuration settings.
          * @param dirs A constant reference to a PublicSettings::ReferenceDirectories object containing the reference directories.
          * @return An Expected object containing a Config::Settings object if the YAML file was successfully parsed and the configuration settings were loaded, or an error otherwise.
@@ -80,17 +86,17 @@ class MRDOCS_DECL
             std::string_view configYaml,
             ReferenceDirectories const& dirs);
 
-        /**
-         * @brief Loads the public configuration settings from the specified file.
-         *
-         * This function takes a file path and a set of reference directories as input.
-         * It reads the file and loads the configuration settings into a Config::Settings object.
-         * The reference directories are used to resolve any relative paths in the configuration settings.
-         *
-         * @param s A reference to a Config::Settings object where the configuration settings will be loaded.
-         * @param filePath A string view representing the file path of the configuration settings.
-         * @param dirs A constant reference to a PublicSettings::ReferenceDirectories object containing the reference directories.
-         * @return An Expected object containing void if the file was successfully read and the configuration settings were loaded, or an error otherwise.
+        /** Loads the public configuration settings from the specified file.
+
+            This function takes a file path and a set of reference directories as input.
+            It reads the file and loads the configuration settings into a Config::Settings object.
+            The reference directories are used to resolve any relative paths in the configuration settings.
+
+            @param s A reference to a Config::Settings object where the configuration settings will be loaded.
+            @param configPath A string view representing the file path of the configuration settings.
+            @param dirs A constant reference to a PublicSettings::ReferenceDirectories object containing the reference directories.
+
+            @return An Expected object containing void if the file was successfully read and the configuration settings were loaded, or an error otherwise.
          */
         static Expected<void>
         load_file(
@@ -120,6 +126,8 @@ class MRDOCS_DECL
 
             This string will always be native style
             and have a trailing directory separator.
+
+            @return The full path to the config file directory.
         */
         std::string
         configDir() const;
@@ -143,6 +151,8 @@ class MRDOCS_DECL
 
             This string will always be native style
             and have a trailing directory separator.
+
+            @return The full path to the output directory.
         */
         std::string
         outputDir() const;