feat: support using directives, using declarations and namespace aliases

Author: fpelliccioni

include/mrdocs/Metadata.hpp

@@ -17,6 +17,7 @@
 // All headers related to
 // metadata extracted from AST
 
+#include <mrdocs/Metadata/Alias.hpp>
 #include <mrdocs/Metadata/Enum.hpp>
 #include <mrdocs/Metadata/Enumerator.hpp>
 #include <mrdocs/Metadata/Expression.hpp>
@@ -37,6 +38,7 @@
 #include <mrdocs/Metadata/Template.hpp>
 #include <mrdocs/Metadata/Type.hpp>
 #include <mrdocs/Metadata/Typedef.hpp>
+#include <mrdocs/Metadata/Using.hpp>
 #include <mrdocs/Metadata/Variable.hpp>
 
 #endif

include/mrdocs/Metadata/Alias.hpp

@@ -0,0 +1,43 @@
+//
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2024 Fernando Pelliccioni ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#ifndef MRDOCS_API_METADATA_ALIAS_HPP
+#define MRDOCS_API_METADATA_ALIAS_HPP
+
+#include <mrdocs/Platform.hpp>
+#include <mrdocs/Metadata/Info.hpp>
+#include <mrdocs/Metadata/Source.hpp>
+#include <mrdocs/Metadata/Type.hpp>
+#include <utility>
+
+namespace clang {
+namespace mrdocs {
+
+/** Info for namespace aliases.
+*/
+struct AliasInfo
+    : IsInfo<InfoKind::Alias>
+    , SourceInfo
+{
+    /** The aliased symbol. */
+    std::unique_ptr<NameInfo> AliasedSymbol;
+
+    //--------------------------------------------
+
+    explicit AliasInfo(SymbolID ID) noexcept
+        : IsInfo(ID)
+    {
+    }
+};
+
+} // mrdocs
+} // clang
+
+#endif

include/mrdocs/Metadata/Info.hpp

@@ -27,6 +27,7 @@
 namespace clang {
 namespace mrdocs {
 
+struct AliasInfo;
 struct NamespaceInfo;
 struct RecordInfo;
 struct FunctionInfo;
@@ -38,6 +39,7 @@ struct SpecializationInfo;
 struct FriendInfo;
 struct EnumeratorInfo;
 struct GuideInfo;
+struct UsingInfo;
 
 /** Info variant discriminator
 */
@@ -64,7 +66,11 @@ enum class InfoKind
     /// The symbol is an enumerator
     Enumerator,
     /// The symbol is a deduction guide
-    Guide
+    Guide,
+    /// The symbol is a namespace alias
+    Alias,
+    /// The symbol is a using declaration and using directive
+    Using,
 };
 
 /** Return the name of the InfoKind as a string.
@@ -177,6 +183,12 @@ struct MRDOCS_VISIBLE
 
     /// Determine if this symbol is a deduction guide.
     constexpr bool isGuide()          const noexcept { return Kind == InfoKind::Guide; }
+
+    /// Determine if this symbol is a namespace alias.
+    constexpr bool isAlias()          const noexcept { return Kind == InfoKind::Alias; }
+
+    /// Determine if this symbol is a using declaration or using directive.
+    constexpr bool isUsing()          const noexcept { return Kind == InfoKind::Using; }
 };
 
 //------------------------------------------------
@@ -230,6 +242,12 @@ struct IsInfo : Info
     /// Determine if this symbol is a deduction guide.
     static constexpr bool isGuide()          noexcept { return K == InfoKind::Guide; }
 
+    /// Determine if this symbol is a namespace alias.
+    static constexpr bool isAlias()          noexcept { return K == InfoKind::Alias; }
+
+    /// Determine if this symbol is a using declaration or using directive.
+    static constexpr bool isUsing()          noexcept { return K == InfoKind::Using; }
+
 protected:
     constexpr explicit IsInfo(SymbolID ID)
         : Info(K, ID)
@@ -282,6 +300,10 @@ visit(
         return visitor.template visit<EnumeratorInfo>();
     case InfoKind::Guide:
         return visitor.template visit<GuideInfo>();
+    case InfoKind::Alias:
+        return visitor.template visit<AliasInfo>();
+    case InfoKind::Using:
+        return visitor.template visit<UsingInfo>();
     default:
         MRDOCS_UNREACHABLE();
     }

include/mrdocs/Metadata/Interface.hpp

@@ -37,6 +37,8 @@ struct Tranche
     std::vector<SymbolID> Variables;
     std::vector<SymbolID> Friends;
     std::vector<SymbolID> Guides;
+    std::vector<SymbolID> Aliases;
+    std::vector<SymbolID> Usings;
 
     ScopeInfo Overloads;
     ScopeInfo StaticOverloads;

include/mrdocs/Metadata/Using.hpp

@@ -0,0 +1,72 @@
+//
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2024 Fernando Pelliccioni ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#ifndef MRDOCS_API_METADATA_USING_HPP
+#define MRDOCS_API_METADATA_USING_HPP
+
+#include <mrdocs/Platform.hpp>
+#include <mrdocs/Metadata/Info.hpp>
+#include <mrdocs/Metadata/Source.hpp>
+#include <mrdocs/Metadata/Type.hpp>
+#include <vector>
+#include <utility>
+
+namespace clang {
+namespace mrdocs {
+
+enum class UsingClass
+{
+    Normal = 0,     // using
+    Typename,       // using typename
+    Enum,           // using enum
+    Namespace       // using namespace (using directive)
+};
+
+static constexpr
+std::string_view
+toString(UsingClass const& value)
+{
+    switch (value)
+    {
+    case UsingClass::Normal:    return "normal";
+    case UsingClass::Typename:  return "typename";
+    case UsingClass::Enum:      return "enum";
+    case UsingClass::Namespace: return "namespace";
+    }
+    return "unknown";
+}
+
+/** Info for using declarations and directives.
+ */
+struct UsingInfo
+    : IsInfo<InfoKind::Using>,
+    SourceInfo
+{
+    /** The kind of using declaration/directive. */
+    UsingClass Class = UsingClass::Normal;
+
+    /** The symbols being "used". */
+    std::vector<SymbolID> UsingSymbols;
+
+    /** The qualifier for a using declaration/directive. */
+    std::unique_ptr<NameInfo> Qualifier;
+
+    //--------------------------------------------
+
+    explicit UsingInfo(SymbolID ID) noexcept
+        : IsInfo(ID)
+    {
+    }
+};
+
+} // mrdocs
+} // clang
+
+#endif

include/mrdocs/MetadataFwd.hpp

@@ -35,6 +35,7 @@ enum class OperatorKind;
 enum class ReferenceKind;
 enum class StorageClassKind;
 
+struct AliasInfo;
 struct BaseInfo;
 struct EnumInfo;
 struct EnumeratorInfo;
@@ -56,6 +57,7 @@ struct TypeInfo;
 struct TypedefInfo;
 struct VariableInfo;
 struct VerbatimBlock;
+struct UsingInfo;
 
 struct ExprInfo;
 template<typename T>

include/mrdocs/mrdocs.natvis

@@ -33,6 +33,8 @@
 		<AlternativeType Name="clang::mrdocs::FriendInfo"/>
 		<AlternativeType Name="clang::mrdocs::EnumeratorInfo"/>
 		<AlternativeType Name="clang::mrdocs::GuideInfo"/>
+		<AlternativeType Name="clang::mrdocs::AliasInfo"/>
+		<AlternativeType Name="clang::mrdocs::UsingInfo"/>
 
 		<DisplayString>{Kind,en} {Name} (ID = {id})</DisplayString>
 
@@ -49,6 +51,8 @@
 		    <ExpandedItem Condition="Kind == InfoKind::Friend">(FriendInfo*)this,view(noinherit)</ExpandedItem>
 		    <ExpandedItem Condition="Kind == InfoKind::Enumerator">(EnumeratorInfo*)this,view(noinherit)</ExpandedItem>
 		    <ExpandedItem Condition="Kind == InfoKind::Guide">(GuideInfo*)this,view(noinherit)</ExpandedItem>
+		    <ExpandedItem Condition="Kind == InfoKind::Alias">(AliasInfo*)this,view(noinherit)</ExpandedItem>
+		    <ExpandedItem Condition="Kind == InfoKind::Using">(UsingInfo*)this,view(noinherit)</ExpandedItem>
 		</Expand>
 	</Type>
 

mrdocs.rnc

@@ -5,6 +5,7 @@
 #
 # Copyright (c) 2023 Klemens Morgenstern ([email protected])
 # Copyright (c) 2023 Krystian Stasiowski ([email protected])
+# Copyright (c) 2024 Fernando Pelliccioni ([email protected])
 #
 # Official repository: https://github.com/cppalliance/mrdocs
 #
@@ -212,6 +213,37 @@ grammar
 
     #---------------------------------------------
 
+    Alias =
+        element alias
+        {
+            Name,
+            Access ?,
+            ID,
+            Location *,
+            Javadoc ?,
+            element aliased
+            {
+                attribute name { text },
+                attribute id { text }
+            }
+        }
+
+    #---------------------------------------------
+
+    Using =
+        element using
+        {
+            Access ?,
+            ID,
+            Location *,
+            Javadoc ?,
+            attribute class { "using" | "using typename" | "using enum" | "using namespace" },
+            attribute qualifier { text } ?,
+            element named { ID } *
+        }
+
+    #---------------------------------------------
+
     Symbol =
     (
         attribute Tag { text },
@@ -301,6 +333,8 @@ grammar
             Var            |
             Guide          |
             Template       |
+            Alias          |
+            Using          |
             Specialization
         )*
 
@@ -315,6 +349,8 @@ grammar
             Guide          |
             Template       |
             Friend         |
+            Alias          |
+            Using          |
             Specialization
         )*
 

share/mrdocs/addons/generator/asciidoc/partials/signature/alias.adoc.hbs

@@ -0,0 +1 @@
+namespace {{symbol.name}} = {{>name-info symbol.aliasedSymbol}}

share/mrdocs/addons/generator/asciidoc/partials/signature/using.adoc.hbs

@@ -0,0 +1,5 @@
+{{#if (eq symbol.class "namespace")}}
+using namespace {{#if symbol.qualifier}}{{>name-info symbol.qualifier}}::{{/if}}{{symbol.name}}
+{{else}}
+using {{#if (eq symbol.class "typename")}}typename {{/if}}{{#if (eq symbol.class "enum")}}enum {{/if}}{{#if symbol.qualifier}}{{>name-info symbol.qualifier}}::{{/if}}{{symbol.name}}
+{{/if}}