auto-relates option

#feat

Author: alandefreitas

docs/mrdocs.schema.json

@@ -17,6 +17,16 @@
       "title": "Use the first line of the comment as the brief",
       "type": "boolean"
     },
+    "auto-relates": {
+      "default": true,
+      "description": "When set to `true`, MrDocs automatically finds non-member functions that are related to the current class.",
+      "enum": [
+        true,
+        false
+      ],
+      "title": "Automatically find non-member functions",
+      "type": "boolean"
+    },
     "base-url": {
       "default": "",
       "description": "Base URL for links to source code. The base URL is used to create links to the source code in the documentation. The base URL is combined with the path to the source file to create the link.",

include/mrdocs/Corpus.hpp

@@ -350,6 +350,35 @@ class MRDOCS_VISIBLE
         return temp;
     }
 
+    /** Return a qualified name from the specified context.
+
+        This function returns the qualified name
+        of the specified Info `I` from the context
+        specified by the SymbolID `context`.
+
+        If the context is a parent of `I`, the
+        qualified name is constructed relative to
+        the context. For instance, if `I` is `A::B::C::D`
+        and context is `A::B`, the result is `C::D`.
+
+        If the context is not a parent of `I`, the
+        qualified name is constructed relative to
+        the global namespace with the prefix `::`.
+     */
+    virtual
+    void
+    qualifiedName(
+        Info const& I,
+        SymbolID const& context,
+        std::string& result) const = 0;
+
+    std::string
+    qualifiedName(Info const& I, SymbolID const& context) const
+    {
+        std::string temp;
+        qualifiedName(I, context, temp);
+        return temp;
+    }
 };
 
 //------------------------------------------------

include/mrdocs/Metadata/Info/Record.hpp

@@ -291,6 +291,10 @@ struct RecordInfo final
     */
     std::vector<BaseInfo> Bases;
 
+    /** List of derived classes
+     */
+    std::vector<SymbolID> Derived;
+
     RecordInterface Interface;
 
     //--------------------------------------------
@@ -347,6 +351,7 @@ tag_invoke(
     io.map("defaultAccess", getDefaultAccessString(I.KeyKind));
     io.map("isTypedef", I.IsTypeDef);
     io.map("bases", dom::LazyArray(I.Bases, domCorpus));
+    io.map("derived", dom::LazyArray(I.Derived, domCorpus));
     io.map("interface", I.Interface);
     io.map("template", I.Template);
 }

include/mrdocs/Metadata/Javadoc.hpp

@@ -1808,7 +1808,7 @@ tag_invoke(
     io.defer("description", [&I, domCorpus] {
         return dom::LazyArray(I.blocks, domCorpus);
     });
-    if (I.brief)
+    if (I.brief && !I.brief->children.empty())
     {
         io.map("brief", I.brief);
     }

include/mrdocs/Metadata/Type.hpp

@@ -562,15 +562,20 @@ innerTypePtr(TypeInfo& TI) noexcept;
     The innermost type is the type which is not
     modified by any specifiers (e.g. "int" in
     "pointer to const int").
+
+    If the type has an inner type, we recursively
+    call this function until we reach the innermost
+    type. If the type has no inner type, we return
+    the current type.
 */
 MRDOCS_DECL
-std::optional<std::reference_wrapper<Polymorphic<TypeInfo> const>>
-innermostType(TypeInfo const& TI) noexcept;
+Polymorphic<TypeInfo> const&
+innermostType(Polymorphic<TypeInfo> const& TI) noexcept;
 
-/// @copydoc innermostType(TypeInfo const&)
+/// @copydoc innermostType(Polymorphic<TypeInfo> const&)
 MRDOCS_DECL
-std::optional<std::reference_wrapper<Polymorphic<TypeInfo>>>
-innermostType(TypeInfo& TI) noexcept;
+Polymorphic<TypeInfo>&
+innermostType(Polymorphic<TypeInfo>& TI) noexcept;
 
 // VFALCO maybe we should rename this to `renderType` or something?
 MRDOCS_DECL

share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs

@@ -79,16 +79,20 @@
 |===
 
 {{/if}}
-{{! Relates symbols }}
-{{#if symbol.doc.relates }}
-{{#> markup/dynamic-level-h }}Non-Member Of{{/markup/dynamic-level-h}}
+{{! Derived classes }}
+{{#if symbol.derived}}
+{{#> markup/dynamic-level-h }}Derived Classes{{/markup/dynamic-level-h}}
 [,cols=2]
 |===
 | Name
 | Description
-{{#each symbol.doc.relates }}
-| {{> javadoc/reference }}
-| {{> javadoc/inline-brief symbol.doc.brief }}
+{{#each symbol.derived}}
+| {{#if url~}}
+{{#>markup/a href=url}}{{#>markup/code}}{{> symbol/name-info . nolink=true}}{{/markup/code}}{{/markup/a}}
+{{else~}}
+{{> symbol/name-info . nolink=true}}
+{{/if}}
+| {{> javadoc/inline-brief doc.brief }}
 {{/each}}
 |===
 
@@ -101,7 +105,7 @@
 {{! Using symbols }}
 {{#if symbol.shadows}}
 {{#> markup/dynamic-level-h }}Introduced Symbols{{/markup/dynamic-level-h}}
-
+[cols=2]
 |===
 | Name
 {{#each symbol.shadows}}
@@ -113,6 +117,7 @@
 {{! Exceptions }}
 {{#if symbol.doc.exceptions}}
 {{#> markup/dynamic-level-h }}Exceptions{{/markup/dynamic-level-h}}
+[cols=2]
 |===
 | Name
 | Thrown on
@@ -140,6 +145,7 @@
 {{! Template Parameters }}
 {{#if symbol.doc.tparams}}
 {{#> markup/dynamic-level-h }}Template Parameters{{/markup/dynamic-level-h}}
+[cols=2]
 |===
 | Name
 | Description
@@ -153,6 +159,7 @@
 {{! Parameters }}
 {{#if symbol.doc.params}}
 {{#> markup/dynamic-level-h }}Parameters{{/markup/dynamic-level-h}}
+[cols=2]
 |===
 | Name
 | Description

share/mrdocs/addons/generator/html/partials/symbol.html.hbs

@@ -106,10 +106,10 @@
 </table>
 </div>
 {{/if}}
-{{! Relates symbols }}
-{{#if symbol.doc.relates }}
+{{! Derived classes }}
+{{#if symbol.derived}}
 <div>
-{{#> markup/dynamic-level-h }}Non-Member Of{{/markup/dynamic-level-h}}
+{{#> markup/dynamic-level-h }}Derived Classes{{/markup/dynamic-level-h}}
 <table>
 <thead>
 <tr>
@@ -118,8 +118,12 @@
 </tr>
 </thead>
 <tbody>
-{{#each symbol.doc.relates }}
-<tr><td>{{> javadoc/reference }}</td><td>{{> javadoc/inline-brief symbol.doc.brief }}</td></tr>
+{{#each symbol.derived}}
+<tr><td>{{#if url~}}
+    {{#>markup/a href=url}}{{#>markup/code}}{{> symbol/name-info . nolink=true}}{{/markup/code}}{{/markup/a}}
+    {{else~}}
+    {{> symbol/name-info . nolink=true}}
+{{/if}}</td><td>{{> javadoc/inline-brief doc.brief }}</td></tr>
 {{/each}}
 </tbody>
 </table>

src/lib/Lib/ConfigOptions.json

@@ -170,6 +170,13 @@
         "details": "When set to `true`, MrDocs uses the first line (until the first dot, question mark, or exclamation mark) of the comment as the brief of the symbol. When set to `false`, a explicit @brief command is required.",
         "type": "bool",
         "default": true
+      },
+      {
+        "name": "auto-relates",
+        "brief": "Automatically find non-member functions",
+        "details": "When set to `true`, MrDocs automatically finds non-member functions that are related to the current class.",
+        "type": "bool",
+        "default": true
       }
     ]
   },

src/lib/Lib/CorpusImpl.cpp

@@ -18,11 +18,13 @@
 #include "lib/Metadata/Finalizers/SortMembersFinalizer.hpp"
 #include "lib/Metadata/Finalizers/JavadocFinalizer.hpp"
 #include "lib/Metadata/Finalizers/NamespacesFinalizer.hpp"
+#include "lib/Metadata/Finalizers/DerivedFinalizer.hpp"
 #include "lib/Support/Report.hpp"
 #include "lib/Support/Chrono.hpp"
 #include <mrdocs/Metadata.hpp>
 #include <mrdocs/Support/Error.hpp>
 #include <mrdocs/Support/ThreadPool.hpp>
+#include <mrdocs/Support/Algorithm.hpp>
 #include <chrono>
 
 namespace clang::mrdocs {
@@ -869,6 +871,57 @@ qualifiedName(Info const& I, std::string& result) const
     }
 }
 
+void
+CorpusImpl::
+qualifiedName(
+    Info const& I,
+    SymbolID const& context,
+    std::string& result) const
+{
+    if (context == SymbolID::global)
+    {
+        qualifiedName(I, result);
+        return;
+    }
+
+    result.clear();
+    if (!I.id || I.id == SymbolID::global)
+    {
+        return;
+    }
+
+    if (I.Parent &&
+        !is_one_of(I.Parent, {SymbolID::global, context}) &&
+        I.id != context)
+    {
+        if (Info const* PI = find(I.Parent))
+        {
+            qualifiedName(*PI, context, result);
+            result += "::";
+        }
+    }
+
+    if (I.id == context)
+    {
+        return;
+    }
+
+    if (I.Parent == SymbolID::global)
+    {
+        result += "::";
+    }
+    if (!I.Name.empty())
+    {
+        result += I.Name;
+    }
+    else
+    {
+        result += "<unnamed ";
+        result += toString(I.Kind);
+        result += ">";
+    }
+}
+
 void
 CorpusImpl::finalize()
 {
@@ -892,6 +945,12 @@ CorpusImpl::finalize()
         finalizer.build();
     }
 
+    {
+        report::debug("Finalizing auto-relates");
+        DerivedFinalizer finalizer(*this);
+        finalizer.build();
+    }
+
     if (config->sortMembers)
     {
         report::debug("Finalizing sorted members");

src/lib/Lib/CorpusImpl.hpp

@@ -61,6 +61,7 @@ class CorpusImpl final : public Corpus
     friend class SortMembersFinalizer;
     friend class JavadocFinalizer;
     friend class NamespacesFinalizer;
+    friend class DerivedFinalizer;
 
 public:
     /** Constructor.
@@ -175,6 +176,12 @@ class CorpusImpl final : public Corpus
         Info const& I,
         std::string& result) const override;
 
+    void
+    qualifiedName(
+        Info const& I,
+        SymbolID const& context,
+        std::string& result) const override;
+
     /** Finalize the corpus.
     */
     void