Info ExtractionMode

#feat

Author: alandefreitas

include/mrdocs/Metadata/ExtractionMode.hpp

@@ -0,0 +1,114 @@
+//
+// This is a derivative work. originally part of the LLVM Project.
+// 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) 2023 Vinnie Falco ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#ifndef MRDOCS_API_METADATA_EXTRACTIONMODE_HPP
+#define MRDOCS_API_METADATA_EXTRACTIONMODE_HPP
+
+#include <mrdocs/Platform.hpp>
+#include <mrdocs/Dom.hpp>
+#include <string_view>
+
+namespace clang::mrdocs {
+
+/** Determine why a symbol is extracted
+
+    The enum constants are ordered by specificity, with
+    the least specific at the beginning and the most
+    specific at the end.
+
+ */
+enum class ExtractionMode
+{
+    /// We're extracting the current symbol even though it
+    /// doesn't pass all filters because it's a direct dependency
+    /// of a symbol that does pass all filters and needs
+    /// information about it (e.g.: base classes outside the filters)
+    Dependency,
+
+    /// We're extracting the current symbol because it passes
+    /// all filters
+    Regular,
+
+    /// We're extracting the current symbol because it passes
+    /// all filters, but we should also tag it as see-below
+    /// because it passes one of the see-below filters
+    SeeBelow,
+
+    /// We're extracting the current symbol because it passes
+    /// all filters, but we should also tag it as
+    /// implementation-defined because one of its parents
+    /// matches the implementation-defined filter
+    ImplementationDefined,
+};
+
+/** Return the name of the InfoKind as a string.
+ */
+constexpr
+std::string_view
+toString(ExtractionMode kind) noexcept
+{
+    switch(kind)
+    {
+    case ExtractionMode::Dependency:
+        return "dependency";
+    case ExtractionMode::Regular:
+        return "regular";
+    case ExtractionMode::SeeBelow:
+        return "see-below";
+    case ExtractionMode::ImplementationDefined:
+        return "implementation-defined";
+    }
+    MRDOCS_UNREACHABLE();
+}
+
+/** Return the InfoKind from a @ref dom::Value string.
+ */
+inline
+void
+tag_invoke(
+    dom::ValueFromTag,
+    dom::Value& v,
+    ExtractionMode kind)
+{
+    v = toString(kind);
+}
+
+/** Compare ExtractionModes and returns the least specific
+
+    This function returns the least specific of the two
+    ExtractionModes in terms of number of filters passed.
+ */
+constexpr
+ExtractionMode
+leastSpecific(ExtractionMode const a, ExtractionMode const b) noexcept
+{
+    using IT = std::underlying_type_t<ExtractionMode>;
+    return static_cast<ExtractionMode>(
+            std::min(static_cast<IT>(a), static_cast<IT>(b)));
+}
+
+/** Compare ExtractionModes and returns the most specific
+
+    This function returns the most specific of the two
+    ExtractionModes in terms of number of filters passed.
+ */
+constexpr
+ExtractionMode
+mostSpecific(ExtractionMode const a, ExtractionMode const b) noexcept
+{
+    using IT = std::underlying_type_t<ExtractionMode>;
+    return static_cast<ExtractionMode>(
+            std::max(static_cast<IT>(a), static_cast<IT>(b)));
+}
+
+} // clang::mrdocs
+
+#endif

include/mrdocs/Metadata/Info.hpp

@@ -17,15 +17,12 @@
 #include <mrdocs/Metadata/Javadoc.hpp>
 #include <mrdocs/Metadata/Specifiers.hpp>
 #include <mrdocs/Metadata/Symbols.hpp>
+#include <mrdocs/Metadata/ExtractionMode.hpp>
 #include <mrdocs/Support/Visitor.hpp>
-#include <array>
 #include <memory>
 #include <string>
-#include <string_view>
-#include <vector>
 
-namespace clang {
-namespace mrdocs {
+namespace clang::mrdocs {
 
 /* Forward declarations
  */
@@ -74,7 +71,7 @@ struct MRDOCS_VISIBLE
 
     /** Kind of declaration.
     */
-    InfoKind Kind;
+    InfoKind Kind = InfoKind::None;
 
     /** Declaration access.
 
@@ -87,18 +84,19 @@ struct MRDOCS_VISIBLE
     */
     AccessKind Access = AccessKind::None;
 
-    /** Implicitly extracted flag.
+    /** Determine why a symbol is extracted.
 
-        This flag distinguishes primary `Info` from its dependencies.
+        This flag distinguishes `Info` from its dependencies and
+        indicates why it was extracted.
 
-        A primary `Info` is one which was extracted during AST traversal
-        because it satisfied all configured conditions to be extracted.
+        Non-dependencies can be extracted in normal mode,
+        see-below mode, or implementation-defined mode.
 
-        An `Info` dependency is one which does not meet the configured
+        A dependency is a symbol which does not meet the configured
         conditions for extraction, but had to be extracted due to it
         being used transitively by a primary `Info`.
     */
-    bool Implicit = false;
+    ExtractionMode Extraction = ExtractionMode::Dependency;
 
     /** The parent symbol, if any.
 
@@ -228,7 +226,14 @@ tag_invoke(
     Info const& I,
     DomCorpus const* domCorpus);
 
-} // mrdocs
-} // clang
+/** Compare two Info objects
+ */
+MRDOCS_DECL
+bool
+operator<(
+    Info const& lhs,
+    Info const& rhs) noexcept;
+
+} // clang::mrdocs
 
 #endif

share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs

@@ -53,7 +53,7 @@
 [,cols=2]
 |===
 |Name |Description
-{{#each symbol.members}}
+{{#each (filter_by symbol.members "isRegular" "isSeeBelow")}}
 {{#if (ne kind "enum-constant")}}
 |xref:{{{anchor}}}[`{{>symbol/name . nolink=true}}`]
 {{else}}
@@ -145,7 +145,7 @@
 {{else}}
 {{#with (flattenUnique symbol.members "doc.tparams" "name") as |allTParams|}}
 {{#if (ne (len allTParams) 0)}}
-{{#> markup/dynamic-level-h }}Parameters{{/markup/dynamic-level-h}}
+{{#> markup/dynamic-level-h }}Template Parameters{{/markup/dynamic-level-h}}
 
 |===
 | Name | Description

share/mrdocs/addons/generator/common/partials/symbol/members-table.hbs

@@ -11,7 +11,7 @@
 
     See: https://mrdocs.com/docs/mrdocs/develop/generators.html#dom_reference
 --}}
-{{#if members}}
+{{#if (any_of_by members "isRegular" "isSeeBelow")}}
 {{#>markup/h level=(select @root.config.multipage 1 2)}}{{title}}{{/markup/h}}
 {{#>markup/table cols=2}}
 {{#>markup/thead}}
@@ -21,7 +21,7 @@
 {{/markup/tr}}
 {{/markup/thead}}
 {{#>markup/tbody}}
-{{#each (sort_by members "name")}}
+{{#each (filter_by (sort_by members "name") "isRegular" "isSeeBelow")}}
 {{> symbol/detail/members-table-row .}}
 {{/each}}
 {{/markup/tbody}}

share/mrdocs/addons/generator/common/partials/symbol/name-info.hbs

@@ -1,6 +1,10 @@
 {{!--
     Renders a Name Info object.
 
+    Name Info objects are typically fields of a Type Object.
+    They carry information about the Symbol the type
+    refers to.
+
     Expected Context: {Name Info Object}
 
     Optional parameters:
@@ -14,9 +18,11 @@
 {{#if prefix~}}
     {{> symbol/name-info prefix nolink=nolink~}}::
 {{~/if~}}
-{{#if (contains (arr "see-below" "implementation-defined") name)~}}
+{{#if symbol.isSeeBelow ~}}
+    {{ str '_'}}see-below{{ str '_'~}}
+{{else if symbol.isImplementationDefined~}}
     {{! These are special names that should not be linked. }}
-    {{ str '_'}}{{name}}{{ str '_'~}}
+    {{ str '_'}}implementation-defined{{ str '_'~}}
 {{else~}}
     {{! Render the name of the symbol. ~}}
     {{#if (and symbol.url (not nolink))~}}

share/mrdocs/addons/generator/html/partials/symbol.html.hbs

@@ -65,7 +65,7 @@
 </tr>
 </thead>
 <tbody>
-{{#each symbol.members}}
+{{#each (filter_by symbol.members "isRegular" "isSeeBelow")}}
 <tr>
 {{#if (ne kind "enum-constant")}}
 <td><a href="#{{anchor}}">{{>symbol/name . nolink=true}}</a></td>

src/lib/Metadata/Info.cpp

@@ -71,7 +71,11 @@ tag_invoke(
     }
     io.map("kind", I.Kind);
     io.map("access", I.Access);
-    io.map("implicit", I.Implicit);
+    io.map("extraction", I.Extraction);
+    io.map("isRegular", I.Extraction == ExtractionMode::Regular);
+    io.map("isSeeBelow", I.Extraction == ExtractionMode::SeeBelow);
+    io.map("isImplementationDefined", I.Extraction == ExtractionMode::ImplementationDefined);
+    io.map("isDependency", I.Extraction == ExtractionMode::Dependency);
     if (I.Parent)
     {
         io.map("parent", I.Parent);