refactor: UsingInfo uses introduced NameInfo

Author: alandefreitas

include/mrdocs/Metadata/Info/NamespaceAlias.hpp

@@ -23,7 +23,11 @@ namespace clang::mrdocs {
 struct NamespaceAliasInfo final
     : InfoCommonBase<InfoKind::NamespaceAlias>
 {
-    /** The aliased symbol. */
+    /** The aliased symbol.
+
+        This is another namespace that might or might
+        not be in the same project.
+     */
     Polymorphic<NameInfo> AliasedSymbol;
 
     //--------------------------------------------

include/mrdocs/Metadata/Info/Using.hpp

@@ -55,21 +55,67 @@ tag_invoke(
 
 
 /** Info for using declarations.
+
+    For instance, the following code:
+
+    @code
+    using A::f; // where f is a function in namespace A
+    @endcode
+
+    would be represented by a `UsingInfo` object.
+
+    Using-declarations can be used to introduce namespace
+    members into other namespaces and block scopes, or to
+    introduce base class members into derived class definitions,
+    or to introduce enumerators into namespaces, block,
+    and class scopes.
+
  */
 struct UsingInfo final
     : InfoCommonBase<InfoKind::Using>
 {
-    /** The kind of using declaration.
+    /** The using declaration.
     */
     UsingClass Class = UsingClass::Normal;
 
-    /** The symbols being "used".
-    */
-    std::vector<SymbolID> UsingSymbols;
+    /** The symbol being introduced.
+
+        This is the symbol that is being "used" or
+        introduced into the current scope.
+
+        Note that this can be a qualified name, such as
+        `A::f` in the example above.
+     */
+    Polymorphic<NameInfo> IntroducedName;
+
+    /** The shadow declarations.
+
+        A using declaration can refer to and introduce
+        multiple symbols into the current context.
+
+        These multiple symbols are considered a special
+        case of declarations: "shadow declarations".
+
+        This typically happens when there are
+        conflicting symbol names in the scope
+        being introduced, such as:
+
+        * Overloaded functions: the base namespace contains
+          overloaded functions.
+        * Name conflicts: the base scope contains a function
+          and a type.
+        * Enums: a using enum declaration can refer to
+          multiple enumerators.
+
+       Also note that more shadow declarations can be
+       introduced later in the same scope, after
+       the using declaration.
 
-    /** The qualifier for a using declaration.
+       The shadow declarations here are only those
+       that are shadowed at the point where the
+       using declaration is located.
     */
-    Polymorphic<NameInfo> Qualifier;
+    std::vector<SymbolID> ShadowDeclarations;
 
     //--------------------------------------------
 
@@ -94,8 +140,8 @@ tag_invoke(
 {
     tag_invoke(t, io, dynamic_cast<Info const&>(I), domCorpus);
     io.map("usingClass", I.Class);
-    io.map("shadows", dom::LazyArray(I.UsingSymbols, domCorpus));
-    io.map("qualifier", I.Qualifier);
+    io.map("shadows", dom::LazyArray(I.ShadowDeclarations, domCorpus));
+    io.map("qualifier", I.IntroducedName);
 }
 
 /** Map the UsingInfo to a @ref dom::Value object.

src/lib/Gen/xml/XMLWriter.cpp

@@ -471,9 +471,9 @@ XMLWriter::
     }
 
     std::string qualifierStr;
-    if (I.Qualifier)
+    if (I.IntroducedName)
     {
-        qualifierStr = toString(*I.Qualifier);
+        qualifierStr = toString(*I.IntroducedName);
     }
 
     constexpr std::string_view usingTagName = "using";
@@ -488,7 +488,7 @@ XMLWriter::
 
     writeJavadoc(I.javadoc);
 
-    for (auto const& id : I.UsingSymbols)
+    for (auto const& id : I.ShadowDeclarations)
         tags_.write("named", {}, { id });
 
     tags_.close(usingTagName);

src/lib/Metadata/Finalizers/JavadocFinalizer.cpp

@@ -744,13 +744,13 @@ finalizeInfoData(InfoTy& I)
     {
         finalize(I.AliasedSymbol);
     }
-    if constexpr (requires { I.Qualifier; })
+    if constexpr (requires { I.IntroducedName; })
     {
-        finalize(I.Qualifier);
+        finalize(I.IntroducedName);
     }
-    if constexpr (requires { I.UsingSymbols; })
+    if constexpr (requires { I.ShadowDeclarations; })
     {
-        finalize(I.UsingSymbols);
+        finalize(I.ShadowDeclarations);
     }
     if constexpr (requires { I.Deduced; })
     {

src/lib/Metadata/Info/Using.cpp

@@ -39,14 +39,14 @@ merge(UsingInfo& I, UsingInfo&& Other)
 {
     MRDOCS_ASSERT(canMerge(I, Other));
     merge(I.asInfo(), std::move(Other.asInfo()));
-    reduceSymbolIDs(I.UsingSymbols, std::move(Other.UsingSymbols));
+    reduceSymbolIDs(I.ShadowDeclarations, std::move(Other.ShadowDeclarations));
     if (I.Class == UsingClass::Normal)
     {
         I.Class = Other.Class;
     }
-    if (!I.Qualifier)
+    if (!I.IntroducedName)
     {
-        I.Qualifier = std::move(Other.Qualifier);
+        I.IntroducedName = std::move(Other.IntroducedName);
     }
 }