feat: sort-namespace-members-by option

fix #988

Author: alandefreitas

docs/mrdocs.schema.json

@@ -419,12 +419,12 @@
     },
     "sort-members": {
       "default": true,
-      "description": "When set to `true`, sort the members of a record or namespace by name and parameters. When set to `false`, the members are included in the declaration order they are extracted.",
+      "description": "When set to `true`, sort the members of a record by the criterion determined in the `sort-members-by` option. When set to `false`, the members are included in the declaration order they are extracted.",
       "enum": [
         true,
         false
       ],
-      "title": "Sort the members of a record or namespace",
+      "title": "Sort the members of a record",
       "type": "boolean"
     },
     "sort-members-assignment-1st": {
@@ -439,12 +439,12 @@
     },
     "sort-members-by": {
       "default": "name",
-      "description": "If `sort-members` is set to `true`, determine how members of a record or namespace are sorted. When set to `name`, members are sorted by name. When set to `location`, members are sorted by their primary location in the source code, considering the short name of the path and the location in the file.",
+      "description": "If `sort-members` is set to `true`, determine how members of a record are sorted. When set to `name`, members are sorted by name. When set to `location`, members are sorted by their primary location in the source code, considering the short name of the path and the location in the file.",
       "enum": [
         "name",
         "location"
       ],
-      "title": "Determine how members of a record or namespace are sorted"
+      "title": "Determine how members of a record are sorted"
     },
     "sort-members-conversion-last": {
       "default": true,
@@ -486,6 +486,15 @@
       "title": "Sort relational operators last",
       "type": "boolean"
     },
+    "sort-namespace-members-by": {
+      "default": "name",
+      "description": "Although members of namespaces are always sorted, determine how members of a namespace are sorted. When set to `name`, members are sorted by name. When set to `location`, members are sorted by their primary location in the source code, considering the short name of the path and the location in the file.",
+      "enum": [
+        "name",
+        "location"
+      ],
+      "title": "Determine how members of a namespace are sorted"
+    },
     "source-root": {
       "default": "<config-dir>",
       "description": "Path to the root directory of the source code. This path is used as a default for input files and a base for relative paths formed from absolute paths. This should typically be the root directory of the git project, as relative paths formed from it can be used to create links to these source files in the repository. Templates use the `base-url` option to create links to the source code.",

src/lib/ConfigOptions.json

@@ -277,15 +277,26 @@
       },
       {
         "name": "sort-members",
-        "brief": "Sort the members of a record or namespace",
-        "details": "When set to `true`, sort the members of a record or namespace by name and parameters. When set to `false`, the members are included in the declaration order they are extracted.",
+        "brief": "Sort the members of a record",
+        "details": "When set to `true`, sort the members of a record by the criterion determined in the `sort-members-by` option. When set to `false`, the members are included in the declaration order they are extracted.",
         "type": "bool",
         "default": true
       },
       {
         "name": "sort-members-by",
-        "brief": "Determine how members of a record or namespace are sorted",
-        "details": "If `sort-members` is set to `true`, determine how members of a record or namespace are sorted. When set to `name`, members are sorted by name. When set to `location`, members are sorted by their primary location in the source code, considering the short name of the path and the location in the file.",
+        "brief": "Determine how members of a record are sorted",
+        "details": "If `sort-members` is set to `true`, determine how members of a record are sorted. When set to `name`, members are sorted by name. When set to `location`, members are sorted by their primary location in the source code, considering the short name of the path and the location in the file.",
+        "type": "enum",
+        "values": [
+            "name",
+            "location"
+        ],
+        "default": "name"
+      },
+      {
+        "name": "sort-namespace-members-by",
+        "brief": "Determine how members of a namespace are sorted",
+        "details": "Although members of namespaces are always sorted, determine how members of a namespace are sorted. When set to `name`, members are sorted by name. When set to `location`, members are sorted by their primary location in the source code, considering the short name of the path and the location in the file.",
         "type": "enum",
         "values": [
             "name",

src/lib/CorpusImpl.cpp

@@ -964,23 +964,27 @@ CorpusImpl::finalize()
         finalizer.build();
     }
 
+    // Add auto relates for member functions
     {
         report::debug("  - Finalizing auto-relates");
         DerivedFinalizer finalizer(*this);
         finalizer.build();
     }
 
-    if (config->sortMembers)
+    // Sort members: this runs unconditionally because
+    // the members of some symbol types are always sorted.
     {
         report::debug("  - Finalizing sorted members");
         SortMembersFinalizer finalizer(*this);
         finalizer.build();
     }
 
     // Finalize javadoc
-    report::debug("  - Finalizing javadoc");
-    JavadocFinalizer finalizer(*this);
-    finalizer.build();
+    {
+        report::debug("  - Finalizing javadoc");
+        JavadocFinalizer finalizer(*this);
+        finalizer.build();
+    }
 }
 
 } // clang::mrdocs

src/lib/Metadata/Finalizers/SortMembersFinalizer.cpp

@@ -213,7 +213,13 @@ struct SymbolIDCompareFn
         }
 
         // Special cases are handled, so use the configuration criteria
-        switch (corpus_.config->sortMembersBy)
+        Info const* P = corpus_.find(lhs.Parent);
+        bool const isClassMember = P && P->isRecord();
+        auto const generalSortCriteria =
+            isClassMember
+                ? corpus_.config->sortMembersBy
+                : corpus_.config->sortNamespaceMembersBy;
+        switch (generalSortCriteria)
         {
         case clang::mrdocs::PublicSettings::SortSymbolBy::Name:
             if (auto const cmp = lhs.Name <=> rhs.Name; cmp != 0)
@@ -352,8 +358,11 @@ void
 SortMembersFinalizer::
 operator()(RecordInfo& I)
 {
-    // Sort members of all tranches
-    sortMembers(I.Interface);
+    // Sort members of all tranches if sorting is enabled for records
+    if (corpus_.config->sortMembers)
+    {
+        sortMembers(I.Interface);
+    }
 
     // Recursively sort members of child records and overloads
     for (RecordInfo& RI: toDerivedView<RecordInfo>(I.Interface.Public.Records, corpus_))