cppalliance · alandefreitas · Feb 14, 2025 · Feb 14, 2025 · Feb 14, 2025
diff --git a/docs/mrdocs.schema.json b/docs/mrdocs.schema.json
@@ -93,14 +93,24 @@
     },
     "extract-anonymous-namespaces": {
       "default": true,
-      "description": "Determine whether symbols in anonymous namespaces should be extracted. When set to `always`, symbols in anonymous namespaces are always extracted. When set to `dependency`, symbols in anonymous namespaces are extracted only if they are referenced by the source code. When set to `never`, symbols in anonymous namespaces are never extracted.",
+      "description": "Determine whether symbols in anonymous namespaces should be extracted.",
       "enum": [
         true,
         false
       ],
       "title": "Extraction policy for anonymous namespaces",
       "type": "boolean"
     },
+    "extract-empty-namespaces": {
+      "default": false,
+      "description": "Determine whether empty namespaces without documentation should be extracted.",
+      "enum": [
+        true,
+        false
+      ],
+      "title": "Extraction policy for empty namespaces",
+      "type": "boolean"
+    },
     "extract-local-classes": {
       "default": true,
       "description": "Determine whether records only defined locally in source files should be extracted.",

diff --git a/include/mrdocs/Metadata/Info.hpp b/include/mrdocs/Metadata/Info.hpp
@@ -273,12 +273,13 @@ tag_invoke(
     DomCorpus const* domCorpus)
 {
     MRDOCS_ASSERT(domCorpus);
+    io.map("class", std::string("symbol"));
+    io.map("kind", I.Kind);
     io.map("id", I.id);
     if (!I.Name.empty())
     {
         io.map("name", I.Name);
     }
-    io.map("kind", I.Kind);
     io.map("access", I.Access);
     io.map("extraction", I.Extraction);
     io.map("isRegular", I.Extraction == ExtractionMode::Regular);

diff --git a/include/mrdocs/Metadata/Info/Function.hpp b/include/mrdocs/Metadata/Info/Function.hpp
@@ -235,7 +235,7 @@ tag_invoke(
     {
         io.map("refQualifier", I.RefQualifier);
     }
-    io.map("class", I.Class);
+    io.map("functionClass", I.Class);
     io.map("params", dom::LazyArray(I.Params, domCorpus));
     io.map("return", I.ReturnType);
     io.map("template", I.Template);

diff --git a/include/mrdocs/Metadata/Info/Namespace.hpp b/include/mrdocs/Metadata/Info/Namespace.hpp
@@ -13,6 +13,7 @@
 #define MRDOCS_API_METADATA_NAMESPACE_HPP
 
 #include <mrdocs/Metadata/Info.hpp>
+#include <mrdocs/Metadata/Name.hpp>
 #include <mrdocs/Dom/LazyArray.hpp>
 #include <vector>
 #include <ranges>
@@ -110,7 +111,7 @@ struct NamespaceInfo final
 
     /** Namespaces nominated by using-directives.
     */
-    std::vector<SymbolID> UsingDirectives;
+    std::vector<NameInfo> UsingDirectives;
 
     /** The members of this namespace.
     */
@@ -121,7 +122,8 @@ struct NamespaceInfo final
     {
     }
 
-    auto operator<=>(NamespaceInfo const&) const = default;
+    std::strong_ordering
+    operator<=>(NamespaceInfo const&) const;
 };
 
 MRDOCS_DECL

diff --git a/include/mrdocs/Metadata/Info/Using.hpp b/include/mrdocs/Metadata/Info/Using.hpp
@@ -93,7 +93,7 @@ tag_invoke(
     DomCorpus const* domCorpus)
 {
     tag_invoke(t, io, dynamic_cast<Info const&>(I), domCorpus);
-    io.map("class", I.Class);
+    io.map("usingClass", I.Class);
     io.map("shadows", dom::LazyArray(I.UsingSymbols, domCorpus));
     io.map("qualifier", I.Qualifier);
 }

diff --git a/include/mrdocs/Metadata/Name.hpp b/include/mrdocs/Metadata/Name.hpp
@@ -13,10 +13,9 @@
 #define MRDOCS_API_METADATA_NAME_HPP
 
 #include <mrdocs/Platform.hpp>
-#include <mrdocs/Metadata/Info.hpp>
 #include <mrdocs/Metadata/Type.hpp>
 #include <mrdocs/Metadata/Template.hpp>
-#include <memory>
+#include <mrdocs/Support/Visitor.hpp>
 
 namespace clang::mrdocs {
 
@@ -100,6 +99,12 @@ struct NameInfo
 
     std::strong_ordering
     operator<=>(NameInfo const& other) const;
+
+    bool
+    operator==(NameInfo const& other) const
+    {
+        return std::is_eq(*this <=> other);
+    }
 };
 
 /** Represents a (possibly qualified) symbol name with template arguments.

diff --git a/mrdocs.rnc b/mrdocs.rnc
@@ -228,7 +228,7 @@ grammar
             element aliased
             {
                 attribute name { text },
-                attribute id { text }
+                attribute id { text } ?
             }
         }
 

diff --git a/share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs
@@ -66,7 +66,7 @@
 {{/if}}
 {{! Using directives }}
 {{#if symbol.usingDirectives}}
-{{>symbol/members-table members=symbol.usingDirectives title="Using Directives"}}
+{{>symbol/members-table members=symbol.usingDirectives title="Using Namespace Directives"}}
 
 {{/if}}
 {{! Related symbols }}

diff --git a/share/mrdocs/addons/generator/common/partials/symbol/detail/members-table-impl.hbs b/share/mrdocs/addons/generator/common/partials/symbol/detail/members-table-impl.hbs
@@ -0,0 +1,21 @@
+{{#>markup/table cols=(select includeBrief 2 1)}}
+{{#>markup/thead}}
+{{#>markup/tr~}}
+{{#>markup/th}}Name{{/markup/th}}
+{{#if includeBrief}}
+{{#>markup/th}}Description{{/markup/th}}
+{{/if}}
+{{/markup/tr}}
+{{/markup/thead}}
+{{#>markup/tbody}}
+{{#if isName}}
+{{#each members}}
+{{> symbol/detail/members-table-row . includeBrief=false isName=true}}
+{{/each}}
+{{ else }}
+{{#each (filter_by members "isRegular" "isSeeBelow")}}
+{{> symbol/detail/members-table-row . includeBrief=../includeBrief isName=false}}
+{{/each}}
+{{/if}}
+{{/markup/tbody}}
+{{/markup/table}}
diff --git a/share/mrdocs/addons/generator/common/partials/symbol/detail/members-table-row.hbs b/share/mrdocs/addons/generator/common/partials/symbol/detail/members-table-row.hbs
@@ -1,12 +1,20 @@
 {{! Helper for "info-list": renders a symbol as a row in a table of members }}
-{{#>markup/tr~}}
-{{#>markup/td}}
-{{! Member name, linked to its documentation }}
-{{#>markup/a href=url}}{{#>markup/code}}{{>symbol/name . nolink=true}}{{/markup/code}}{{/markup/a}} {{>symbol/special-function-suffix .}}
-{{~/markup/td}}
-{{#if (eq includeBrief true)}}
+{{#>markup/tr}}
 {{#>markup/td~}}
-{{{~doc.brief}}}
-{{/markup/td~}}
+{{~#if isName~}}
+{{~#if symbol.url~}}
+{{~#>markup/a href=symbol.url}}{{#>markup/code}}{{> symbol/name-info . nolink=true}}{{/markup/code}}{{/markup/a~}}
+{{~else~}}
+{{~> symbol/name-info . nolink=true~}}
+{{~/if~}}
+{{~else~}}
+{{~#>markup/a href=url}}{{#>markup/code}}{{>symbol/name . nolink=true}}{{/markup/code}}{{/markup/a}} {{>symbol/special-function-suffix .~}}
+{{~/if~}}
+{{~/markup/td}}
+{{#if includeBrief~}}
+{{~#>markup/td~}}
+{{{~doc.brief~}}}
+{{~/markup/td}}
 {{/if}}
-{{~/markup/tr}}
+
+{{/markup/tr}}
diff --git a/share/mrdocs/addons/generator/common/partials/symbol/members-table.hbs b/share/mrdocs/addons/generator/common/partials/symbol/members-table.hbs
@@ -4,41 +4,19 @@
     This partials renders each row with the symbol name and brief for
     each member.
 
-    Expected Context: {Symbol Object}
+    Expected Context: {Symbol|NameInfo}[]
+
+    Parameters:
+        members: An array of symbols or nameinfo to render.
 
     Example:
         {{> symbol/members-table symbol }}
 
     See: https://mrdocs.com/docs/mrdocs/develop/generators.html#dom_reference
 --}}
-{{#if (any_of_by members "isRegular" "isSeeBelow")}}
+{{#if members}}
+{{#if (or (eq members[0].class "name") (any_of_by members "isRegular" "isSeeBelow"))}}
 {{#>markup/h level=(select @root.config.multipage 1 2)}}{{title}}{{/markup/h}}
-{{#if (any_of_by members "doc")}}
-{{#>markup/table cols=2}}
-{{#>markup/thead}}
-{{#>markup/tr~}}
-{{#>markup/th}}Name{{/markup/th~}}
-{{#>markup/th}}Description{{/markup/th}}
-{{/markup/tr}}
-{{/markup/thead}}
-{{#>markup/tbody}}
-{{#each (filter_by members "isRegular" "isSeeBelow")}}
-{{> symbol/detail/members-table-row . includeBrief=true}}
-{{/each}}
-{{/markup/tbody}}
-{{/markup/table}}
-{{else}}
-{{#>markup/table cols=1}}
-{{#>markup/thead}}
-{{#>markup/tr~}}
-{{#>markup/th}}Name{{/markup/th}}
-{{/markup/tr}}
-{{/markup/thead}}
-{{#>markup/tbody}}
-{{#each (filter_by members "isRegular" "isSeeBelow")}}
-{{> symbol/detail/members-table-row . includeBrief=false}}
-{{/each}}
-{{/markup/tbody}}
-{{/markup/table}}
-{{/if}}
+{{>symbol/detail/members-table-impl members=members isName=(eq members[0].class "name") includeBrief=(select (any_of_by members "doc") true false) title=title}}
 {{/if}}
+{{/if}}
diff --git a/share/mrdocs/addons/generator/common/partials/symbol/name.hbs b/share/mrdocs/addons/generator/common/partials/symbol/name.hbs
@@ -15,7 +15,7 @@
 
     See: https://mrdocs.com/docs/mrdocs/develop/generators.html#dom_reference
 --}}
-{{#if (and (eq kind "function") (eq class "conversion"))~}}
+{{#if (and (eq kind "function") (eq functionClass "conversion"))~}}
     {{! Conversion operator: "operator" and the type declarator ~}}
     operator {{>type/declarator return nolink=nolink~}}
 {{else if (eq kind "guide")~}}

diff --git a/share/mrdocs/addons/generator/common/partials/symbol/signature/function.hbs b/share/mrdocs/addons/generator/common/partials/symbol/signature/function.hbs
@@ -12,7 +12,7 @@
 {{/if~}}
 {{#if explicitSpec}}{{explicitSpec}}
 {{/if~}}
-{{#if (eq class "normal")}}{{>type/declarator-prefix return}}
+{{#if (eq functionClass "normal")}}{{>type/declarator-prefix return}}
 {{/if~}}
 {{>symbol/name symbol link=(select link link template.primary)}}
 ({{#if isExplicitObjectMemberFunction}}this {{/if}}{{#each params}}{{#unless (and @first @last)}}
@@ -24,7 +24,7 @@
 {{#if isVolatile}} volatile{{/if~}}
 {{#if refQualifier}} {{refQualifier}}{{/if~}}
 {{#if exceptionSpec}} {{exceptionSpec}}{{/if~}}
-{{#if (eq class "normal")}}{{>type/declarator-suffix return}}{{/if~}}
+{{#if (eq functionClass "normal")}}{{>type/declarator-suffix return}}{{/if~}}
 {{#if requires}}
 
 requires {{requires}}{{/if~}}

diff --git a/share/mrdocs/addons/generator/common/partials/symbol/signature/using.hbs b/share/mrdocs/addons/generator/common/partials/symbol/signature/using.hbs
@@ -1,4 +1,4 @@
-using {{#if (contains (arr "typename" "enum") class)}} {{class}}
+using {{#if (contains (arr "typename" "enum") usingClass)}} {{usingClass}}
 {{~/if~}}
 {{~#if qualifier~}}
     {{>symbol/name-info qualifier }}::

diff --git a/share/mrdocs/addons/generator/common/partials/symbol/special-function-suffix.hbs b/share/mrdocs/addons/generator/common/partials/symbol/special-function-suffix.hbs
@@ -15,9 +15,9 @@
 {{#if (eq kind "overloads")~}}
     {{>symbol/special-function-suffix (front members)}}
 {{~else if (eq kind "function")~}}
-    {{#if (eq class "constructor")}}
+    {{#if (eq functionClass "constructor")}}
         {{#>markup/span class="small"}}[constructor]{{/markup/span}}
-    {{~else if (eq class "destructor")~}}
+    {{~else if (eq functionClass "destructor")~}}
         {{#>markup/span class="small"}}[destructor]{{/markup/span}}
     {{~/if~}}
     {{~#if isVirtual~}}

diff --git a/share/mrdocs/addons/generator/html/partials/symbol.html.hbs b/share/mrdocs/addons/generator/html/partials/symbol.html.hbs
@@ -81,7 +81,7 @@
 {{! Using directives }}
 {{#if symbol.usingDirectives}}
 <div>
-{{>symbol/members-table members=symbol.usingDirectives title="Using Directives"}}
+{{>symbol/members-table members=symbol.usingDirectives title="Using Namespace Directives"}}
 
 </div>
 

diff --git a/src/lib/AST/ASTVisitor.cpp b/src/lib/AST/ASTVisitor.cpp
@@ -158,6 +158,8 @@ Info*
 ASTVisitor::
 traverse(UsingDirectiveDecl const* D)
 {
+    MRDOCS_SYMBOL_TRACE(D, context_);
+
     // Find the parent namespace
     ScopeExitRestore s1(mode_, TraversalMode::Dependency);
     Decl const* P = getParent(D);
@@ -174,9 +176,13 @@ traverse(UsingDirectiveDecl const* D)
     Info* NDI = findOrTraverse(ND);
     MRDOCS_CHECK_OR(NDI, nullptr);
 
-    if (std::ranges::find(PNI->UsingDirectives, NDI->id) == PNI->UsingDirectives.end())
+    auto res = toNameInfo(ND);
+    MRDOCS_ASSERT(res);
+    MRDOCS_ASSERT(res->isIdentifier());
+    if (NameInfo NI = *res;
+        std::ranges::find(PNI->UsingDirectives, NI) == PNI->UsingDirectives.end())
     {
-        PNI->UsingDirectives.emplace_back(NDI->id);
+        PNI->UsingDirectives.push_back(std::move(NI));
     }
     return nullptr;
 }

diff --git a/src/lib/AST/ParseRef.cpp b/src/lib/AST/ParseRef.cpp
@@ -385,6 +385,11 @@ class RefParser
     bool
     parseFunctionParameters()
     {
+        // https://en.cppreference.com/w/cpp/language/function
+        // parameter-list:
+        // possibly empty, comma-separated list of the function parameters
+        // (see below for details)
+
         char const* start = ptr_;
         if (!parseLiteral('('))
         {
@@ -549,6 +554,21 @@ class RefParser
     bool
     parseMemberFunctionQualifiers()
     {
+        // https://en.cppreference.com/w/cpp/language/function
+
+        // Parse cv:
+        // const/volatile qualification, only allowed in non-static member
+        // function declarations
+
+        // Parse ref:
+        // ref-qualification, only allowed in non-static member function
+        // declarations
+
+        // Parse except:
+        // dynamic exception specification, dynamic exception specification
+        // or noexcept specification, noexcept specification
+
+
         // Parse potential qualifiers at the end of a function
         // to identify the qualifiers to set
         // ReferenceKind Kind = ReferenceKind::None; and

diff --git a/src/lib/Gen/xml/XMLWriter.cpp b/src/lib/Gen/xml/XMLWriter.cpp
@@ -214,9 +214,12 @@ writeNamespace(
         { "is-inline", "1", I.IsInline}
     });
     writeJavadoc(I.javadoc);
-    for (SymbolID const& id: I.UsingDirectives)
+    for (NameInfo const& NI: I.UsingDirectives)
     {
-        tags_.write("using-directive", {}, { { id } });
+        if (auto const& id = NI.id; id != SymbolID::invalid)
+        {
+            tags_.write("using-directive", {}, { { id } });
+        }
     }
     corpus_.traverse(I, *this);
     tags_.close(namespaceTagName);

diff --git a/src/lib/Lib/ConfigOptions.json b/src/lib/Lib/ConfigOptions.json
@@ -223,10 +223,17 @@
       {
         "name": "extract-anonymous-namespaces",
         "brief": "Extraction policy for anonymous namespaces",
-        "details": "Determine whether symbols in anonymous namespaces should be extracted. When set to `always`, symbols in anonymous namespaces are always extracted. When set to `dependency`, symbols in anonymous namespaces are extracted only if they are referenced by the source code. When set to `never`, symbols in anonymous namespaces are never extracted.",
+        "details": "Determine whether symbols in anonymous namespaces should be extracted.",
         "type": "bool",
         "default": true
       },
+      {
+        "name": "extract-empty-namespaces",
+        "brief": "Extraction policy for empty namespaces",
+        "details": "Determine whether empty namespaces without documentation should be extracted.",
+        "type": "bool",
+        "default": false
+      },
       {
         "name": "inherit-base-members",
         "brief": "Determine how derived classes inherit base members",