refactor: modular ASTVisitor

Author: alandefreitas

.github/workflows/ci.yml

@@ -536,38 +536,59 @@ jobs:
           trace-commands: true
 
       - name: Set up llvm-symbolizer
-        if: ${{ runner.os == 'macOS' }}
+        if: ${{ runner.os != 'Windows' }}
         run: |
           set -x
-
-          # Step 1: Check if llvm-symbolizer is installed
-          if ! command -v llvm-symbolizer &> /dev/null; then
-              echo "llvm-symbolizer is not installed. Installing via Homebrew..."
-              # Step 2: Install llvm if not installed
-              if command -v brew &> /dev/null; then
-                  brew install llvm
-              else
-                  echo "Homebrew is not installed. Please install Homebrew first: https://brew.sh/"
-                  exit 1
-              fi
-          fi
-          
-          # Step 3: Ensure llvm-symbolizer is in your PATH
-          llvm_bin_path=$(brew --prefix)/opt/llvm/bin
-          PATH="$PATH:$llvm_bin_path"
-          LLVM_SYMBOLIZER_PATH=$(which llvm-symbolizer)
-          if [ -z "$LLVM_SYMBOLIZER_PATH" ]; then
-              echo "llvm-symbolizer installation failed or it's not in the PATH."
-              exit 1
+      
+          if [[ $RUNNER_OS == 'macOS' ]]; then
+            # Step 1: Check if llvm-symbolizer is installed
+            if ! command -v llvm-symbolizer &> /dev/null; then
+                echo "llvm-symbolizer is not installed. Installing via Homebrew..."
+                # Step 2: Install llvm if not installed
+                if command -v brew &> /dev/null; then
+                    brew install llvm
+                else
+                    echo "Homebrew is not installed. Please install Homebrew first: https://brew.sh/"
+                    exit 1
+                fi
+            fi
+      
+            # Step 3: Ensure llvm-symbolizer is in your PATH
+            llvm_bin_path=$(brew --prefix)/opt/llvm/bin
+            PATH="$PATH:$llvm_bin_path"
+            LLVM_SYMBOLIZER_PATH=$(which llvm-symbolizer)
+            if [ -z "$LLVM_SYMBOLIZER_PATH" ]; then
+                echo "llvm-symbolizer installation failed or it's not in the PATH."
+                exit 1
+            else
+                echo "llvm-symbolizer found at: $LLVM_SYMBOLIZER_PATH"
+            fi
+          elif [[ $RUNNER_OS == 'Linux' ]]; then
+            # Step 1: Check if llvm-symbolizer is installed
+            if ! command -v llvm-symbolizer &> /dev/null; then
+                echo "llvm-symbolizer is not installed. Installing via apt-get..."
+                apt-get update
+                apt-get install -y llvm
+            fi
+      
+            # Step 2: Ensure llvm-symbolizer is in your PATH
+            LLVM_SYMBOLIZER_PATH=$(which llvm-symbolizer)
+            if [ -z "$LLVM_SYMBOLIZER_PATH" ]; then
+                echo "llvm-symbolizer installation failed or it's not in the PATH."
+                exit 1
+            else
+                echo "llvm-symbolizer found at: $LLVM_SYMBOLIZER_PATH"
+            fi
           else
-              echo "llvm-symbolizer found at: $LLVM_SYMBOLIZER_PATH"
+            echo "Unsupported OS: $RUNNER_OS"
+            exit 1
           fi
-          
+      
           # Step 4: Export LLVM_SYMBOLIZER_PATH environment variable
           export LLVM_SYMBOLIZER_PATH="$LLVM_SYMBOLIZER_PATH"
           echo -e "LLVM_SYMBOLIZER_PATH=$LLVM_SYMBOLIZER_PATH" >> $GITHUB_ENV
           echo "Environment variable LLVM_SYMBOLIZER_PATH set to: $LLVM_SYMBOLIZER_PATH"
-          
+
       - name: Generate Landing Page
         working-directory: docs/website
         run: |

docs/modules/ROOT/pages/design-notes.adoc

@@ -78,7 +78,8 @@ Here are a few constructs MrDocs attempts to understand and document automatical
 * Private APIs
 * Unspecified Return Types
 * Concepts
-* Typedef / Aliases
+* Typedefs
+* Namespace Aliases
 * Constants
 * Automatic Related Types
 * Macros

docs/modules/ROOT/pages/generators.adoc

@@ -499,7 +499,7 @@ When the symbol kind is `friend`, the symbol object has the following additional
 | The friend type.
 |===
 
-When the symbol kind is `alias`, the symbol object has the following additional properties:
+When the symbol kind is `namespace-alias`, the symbol object has the following additional properties:
 
 |===
 | Property | Type | Description
@@ -527,14 +527,14 @@ When the symbol kind is `using`, the symbol object has the following additional
 | The qualifier of the using declaration.
 |===
 
-When the symbol kind is `enumerator`, the symbol object has the following additional properties:
+When the symbol kind is `enum-constant`, the symbol object has the following additional properties:
 
 |===
 | Property | Type | Description
 
 | `initializer`
 | `string`
-| The initializer of the enumerator.
+| The initializer of the enum-constant.
 |===
 
 When the symbol kind is `guide`, the symbol object has the following additional properties:

docs/modules/ROOT/partials/InfoNodes.inc

@@ -73,7 +73,7 @@ INFO(Variable,       Variables,       VARIABLE,       variable,       variables,
 INFO(Field,          Fields,          FIELD,          field,          fields,          The symbol is a field)
 INFO(Specialization, Specializations, SPECIALIZATION, specialization, specializations, The symbol is a template specialization)
 INFO(Friend,         Friends,         FRIEND,         friend,         friends,         The symbol is a friend declaration)
-INFO(Enumerator,     Enumerators,     ENUMERATOR,     enumerator,     enumerators,     The symbol is an enumerator)
+INFO(EnumConstant,   EnumConstants,   ENUM_CONSTANT,  enumerator,     enumerators,     The symbol is an enumerator)
 INFO(Guide,          Guides,          GUIDE,          guide,          guides,          The symbol is a deduction guide)
 INFO(Alias,          Aliases,         ALIAS,          alias,          aliases,         The symbol is a namespace alias)
 INFO(Using,          Usings,          USING,          using,          usings,          The symbol is a using declaration)

docs/mrdocs.schema.json

@@ -111,7 +111,7 @@
     },
     "implementation-defined": {
       "default": [],
-      "description": "Namespaces for symbols rendered as \"implementation-defined\". Symbols in these namespaces are not extracted and are rendered as \"implementation-defined\" in the documentation. This option is used to exclude symbols from the documentation that are considered part of the private API of the project.",
+      "description": "Namespaces for symbols rendered as \"implementation-defined\". Symbols in these are rendered as \"implementation-defined\" in the documentation. This option is used to exclude symbols from the documentation that are considered part of the private API of the project. An \"implementation-defined\" symbol has no documentation page in the output. If any other symbol refers to it, the reference is rendered as \"implementation-defined\".",
       "items": {
         "type": "string"
       },
@@ -130,7 +130,7 @@
     },
     "inaccessible-members": {
       "default": "always",
-      "description": "Determine whether inaccessible members should be extracted. When set to `always`, inaccessible members are always extracted. When set to `dependency`, inaccessible members are extracted only if they are referenced by the source code. When set to `never`, inaccessible members are never extracted.",
+      "description": "Determine whether inaccessible members, such as private members of records, should be extracted. When set to `always`, inaccessible members are always extracted. When set to `dependency`, inaccessible members are extracted only if they are referenced by the source code. When set to `never`, inaccessible members are never extracted.",
       "enum": [
         "always",
         "dependency",
@@ -193,7 +193,7 @@
     },
     "referenced-declarations": {
       "default": "dependency",
-      "description": "Determine whether external declarations should be extracted when they are referenced in the source code. When set to `always`, external declarations are always extracted. When set to `dependency`, external declarations are extracted only if they are referenced by the source code. When set to `never`, external declarations are never extracted.",
+      "description": "Determine whether external declarations should be extracted when they are referenced in the source code. If this option is not `never`, a second pass happens in the extraction process to extract dependencies in the Corpus. When set to `always`, external declarations are always extracted. When set to `dependency`, external declarations are extracted only if they are referenced by the source code. When set to `never`, external declarations are never extracted.",
       "enum": [
         "always",
         "dependency",
@@ -211,7 +211,7 @@
     },
     "see-below": {
       "default": [],
-      "description": "Namespaces for symbols rendered as \"see-below\". Symbols in these namespaces are not extracted and are rendered as \"see-below\" in the documentation. This option is used to exclude symbols from the documentation that are considered part of the private API of the project.",
+      "description": "Namespaces for symbols rendered as \"see-below\". Symbols in these namespaces are rendered as \"see-below\" in the documentation. This option is used to exclude details about symbols from the documentation that are considered part of the private API of the project. In the documentation page for this symbol, the synopsis of the implementation of a \"see-below\" symbol is rendered as \"see-below\". When the symbol is a scope (such as a namespace or record), its members are not listed. The rest of the documentation is rendered as usual.",
       "items": {
         "type": "string"
       },

docs/website/render.js

@@ -46,6 +46,8 @@ if (!fs.existsSync(mrdocsExecutable)) {
 // Read panel snippet files and create documentation
 const absSnippetsDir = path.join(__dirname, 'snippets')
 for (let panel of data.panels) {
+    console.log(`Generating documentation for panel ${panel.source}`)
+
     // Find source file
     const sourcePath = path.join(absSnippetsDir, panel.source)
     assert(sourcePath.endsWith('.cpp'))
@@ -102,6 +104,9 @@ target_compile_features(${sourceBasename} PRIVATE cxx_std_23)
     // Delete these temporary files
     fs.rmSync(mrdocsOutput, {recursive: true});
     fs.unlinkSync(cmakeListsPath);
+
+    console.log(`Documentation generated successfully for panel ${panel.source}`)
+    console.log(`====================================`)
 }
 
 // Render the template with the data containing the snippet data

docs/website/snippets/mrdocs.yml

@@ -1 +1,4 @@
 source-root: .
+input:
+  include:
+    - .

include/mrdocs/Metadata.hpp

@@ -17,10 +17,9 @@
 // All headers related to
 // metadata extracted from AST
 
-#include <mrdocs/Metadata/Alias.hpp>
 #include <mrdocs/Metadata/Concept.hpp>
 #include <mrdocs/Metadata/Enum.hpp>
-#include <mrdocs/Metadata/Enumerator.hpp>
+#include <mrdocs/Metadata/EnumConstant.hpp>
 #include <mrdocs/Metadata/Expression.hpp>
 #include <mrdocs/Metadata/Field.hpp>
 #include <mrdocs/Metadata/Friend.hpp>
@@ -31,10 +30,11 @@
 #include <mrdocs/Metadata/Javadoc.hpp>
 #include <mrdocs/Metadata/Name.hpp>
 #include <mrdocs/Metadata/Namespace.hpp>
+#include <mrdocs/Metadata/NamespaceAlias.hpp>
 #include <mrdocs/Metadata/Overloads.hpp>
 #include <mrdocs/Metadata/Record.hpp>
-#include <mrdocs/Metadata/Specialization.hpp>
 #include <mrdocs/Metadata/Source.hpp>
+#include <mrdocs/Metadata/Specialization.hpp>
 #include <mrdocs/Metadata/Symbols.hpp>
 #include <mrdocs/Metadata/Template.hpp>
 #include <mrdocs/Metadata/Type.hpp>

include/mrdocs/Metadata/Concept.hpp

@@ -15,6 +15,7 @@
 #include <mrdocs/Metadata/Info.hpp>
 #include <mrdocs/Metadata/Expression.hpp>
 #include <mrdocs/Metadata/Source.hpp>
+#include <mrdocs/Metadata/Template.hpp>
 
 namespace clang {
 namespace mrdocs {

include/mrdocs/Metadata/Enumerator.hpp renamed to include/mrdocs/Metadata/EnumConstant.hpp

@@ -8,8 +8,8 @@
 // Official repository: https://github.com/cppalliance/mrdocs
 //
 
-#ifndef MRDOCS_API_METADATA_ENUMERATOR_HPP
-#define MRDOCS_API_METADATA_ENUMERATOR_HPP
+#ifndef MRDOCS_API_METADATA_ENUMCONSTANT_HPP
+#define MRDOCS_API_METADATA_ENUMCONSTANT_HPP
 
 #include <mrdocs/Platform.hpp>
 #include <mrdocs/Metadata/Expression.hpp>
@@ -21,10 +21,10 @@
 namespace clang {
 namespace mrdocs {
 
-/** Info for enumerators.
+/** Info for enum constants.
 */
-struct EnumeratorInfo
-    : InfoCommonBase<InfoKind::Enumerator>
+struct EnumConstantInfo
+    : InfoCommonBase<InfoKind::EnumConstant>
     , SourceInfo
 {
     /** The initializer expression, if any
@@ -33,7 +33,7 @@ struct EnumeratorInfo
 
     //--------------------------------------------
 
-    explicit EnumeratorInfo(SymbolID ID) noexcept
+    explicit EnumConstantInfo(SymbolID ID) noexcept
         : InfoCommonBase(ID)
     {
     }