feat: support @relates

sdkrystian · sdkrystian · commit 8bcfb6e569e5 · 2024-10-11T11:14:29.000-04:00
diff --git a/include/mrdocs/Metadata/Javadoc.hpp b/include/mrdocs/Metadata/Javadoc.hpp
@@ -126,6 +126,7 @@ enum class Kind
     throws,
     details,
     see,
+    related,
     precondition,
     postcondition
 };
@@ -358,6 +359,25 @@ struct Copied : Reference
     }
 };
 
+/** A reference to a related symbol.
+*/
+struct Related : Reference
+{
+    static constexpr Kind static_kind = Kind::related;
+
+    Related(String string_ = String()) noexcept
+        : Reference(std::move(string_), Kind::related)
+    {
+    }
+
+    bool operator==(Related const&) const noexcept = default;
+    bool equals(Node const& other) const noexcept override
+    {
+        return kind == other.kind &&
+            *this == static_cast<const Related&>(other);
+    }
+};
+
 //------------------------------------------------
 //
 // Block nodes
@@ -802,6 +822,8 @@ visit(
         return f.template operator()<Precondition>(std::forward<Args>(args)...);
     case Kind::postcondition:
         return f.template operator()<Postcondition>(std::forward<Args>(args)...);
+    case Kind::related:
+        return f.template operator()<Related>(std::forward<Args>(args)...);
     default:
         return f.template operator()<void>(std::forward<Args>(args)...);
     }
@@ -867,6 +889,8 @@ visit(
         return visitor.template visit<Precondition>();
     case Kind::postcondition:
         return visitor.template visit<Postcondition>();
+    case Kind::related:
+        return visitor.template visit<Related>();
     default:
         MRDOCS_UNREACHABLE();
     }
@@ -901,6 +925,7 @@ struct Overview
     std::vector<See const*> sees;
     std::vector<Precondition const*> preconditions;
     std::vector<Postcondition const*> postconditions;
+    std::vector<Related const*> related;
 };
 
 MRDOCS_DECL dom::String toString(Style style) noexcept;
diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/alias.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/alias.adoc.hbs
@@ -28,3 +28,13 @@
 {{/each}}
 
 {{/if}}
+
+{{#if symbol.doc.related}}
+=={{#unless is_multipage}}={{/unless}} Related
+
+{{#each symbol.doc.related}}
+{{.}}
+
+{{/each}}
+
+{{/if}}
diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/concept.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/concept.adoc.hbs
@@ -28,3 +28,13 @@
 {{/each}}
 
 {{/if}}
+
+{{#if symbol.doc.related}}
+=={{#unless is_multipage}}={{/unless}} Related
+
+{{#each symbol.doc.related}}
+{{.}}
+
+{{/each}}
+
+{{/if}}
diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/enum.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/enum.adoc.hbs
@@ -38,3 +38,13 @@
 {{/each}}
 
 {{/if}}
+
+{{#if symbol.doc.related}}
+=={{#unless is_multipage}}={{/unless}} Related
+
+{{#each symbol.doc.related}}
+{{.}}
+
+{{/each}}
+
+{{/if}}
diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/enumerator.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/enumerator.adoc.hbs
@@ -29,3 +29,13 @@
 {{/each}}
 
 {{/if}}
+
+{{#if symbol.doc.related}}
+=={{#unless is_multipage}}={{/unless}} Related
+
+{{#each symbol.doc.related}}
+{{.}}
+
+{{/each}}
+
+{{/if}}
diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/field.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/field.adoc.hbs
@@ -28,3 +28,13 @@
 {{/each}}
 
 {{/if}}
+
+{{#if symbol.doc.related}}
+=={{#unless is_multipage}}={{/unless}} Related
+
+{{#each symbol.doc.related}}
+{{.}}
+
+{{/each}}
+
+{{/if}}
diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/friend.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/friend.adoc.hbs
@@ -28,3 +28,13 @@
 {{/each}}
 
 {{/if}}
+
+{{#if symbol.doc.related}}
+=={{#unless is_multipage}}={{/unless}} Related
+
+{{#each symbol.doc.related}}
+{{.}}
+
+{{/each}}
+
+{{/if}}
diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/function.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/function.adoc.hbs
@@ -95,3 +95,13 @@
 {{/each}}
 
 {{/if}}
+
+{{#if symbol.doc.related}}
+=={{#unless is_multipage}}={{/unless}} Related
+
+{{#each symbol.doc.related}}
+{{.}}
+
+{{/each}}
+
+{{/if}}
diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/guide.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/guide.adoc.hbs
@@ -28,3 +28,13 @@
 {{/each}}
 
 {{/if}}
+
+{{#if symbol.doc.related}}
+=={{#unless is_multipage}}={{/unless}} Related
+
+{{#each symbol.doc.related}}
+{{.}}
+
+{{/each}}
+
+{{/if}}
diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/record.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/record.adoc.hbs
@@ -48,3 +48,13 @@
 {{/each}}
 
 {{/if}}
+
+{{#if symbol.doc.related}}
+=={{#unless is_multipage}}={{/unless}} Related
+
+{{#each symbol.doc.related}}
+{{.}}
+
+{{/each}}
+
+{{/if}}
diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/typedef.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/typedef.adoc.hbs
@@ -28,3 +28,13 @@
 {{/each}}
 
 {{/if}}
+
+{{#if symbol.doc.related}}
+=={{#unless is_multipage}}={{/unless}} Related
+
+{{#each symbol.doc.related}}
+{{.}}
+
+{{/each}}
+
+{{/if}}
diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/using.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/using.adoc.hbs
@@ -40,3 +40,13 @@
 {{/each}}
 
 {{/if}}
+
+{{#if symbol.doc.related}}
+=={{#unless is_multipage}}={{/unless}} Related
+
+{{#each symbol.doc.related}}
+{{.}}
+
+{{/each}}
+
+{{/if}}
diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/variable.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/variable.adoc.hbs
@@ -28,3 +28,13 @@
 {{/each}}
 
 {{/if}}
+
+{{#if symbol.doc.related}}
+=={{#unless is_multipage}}={{/unless}} Related
+
+{{#each symbol.doc.related}}
+{{.}}
+
+{{/each}}
+
+{{/if}}
diff --git a/src/lib/AST/ParseJavadoc.cpp b/src/lib/AST/ParseJavadoc.cpp
@@ -870,6 +870,38 @@ visitInlineCommandComment(
         }
         return;
     }
+    // KRYSTIAN FIXME: these need to be made inline commands in clang
+    case CommandTraits::KCI_related:
+    case CommandTraits::KCI_relates:
+    {
+        if(! goodArgCount(1, *C))
+            return;
+        // The parsed reference often includes characters
+        // that are not valid in identifiers, so we need to
+        // clean it up.
+        // Find the first character that is not a valid C++
+        // identifier character, and truncate the string there.
+        // This potentially creates two text nodes.
+        auto const s = C->getArgText(0).str();
+        std::string_view ref = parseQualifiedIdentifier(s);
+        bool const hasExtraText = ref.size() != s.size();
+        if (!ref.empty())
+        {
+            // the referenced symbol will be resolved during
+            // the finalization step once all symbols are extracted
+            emplaceText<doc::Related>(
+                C->hasTrailingNewline() && !hasExtraText,
+                std::string(ref));
+        }
+        // Emplace the rest of the string as doc::Text
+        if(hasExtraText)
+        {
+            emplaceText<doc::Text>(
+                C->hasTrailingNewline(),
+                s.substr(ref.size()));
+        }
+        return;
+    }
 
     default:
         break;
@@ -1388,8 +1420,7 @@ JavadocVisitor::
 visitVerbatimLineComment(
     VerbatimLineComment const* C)
 {
-    // VFALCO This doesn't seem to be used
-    //        in any of my codebases, follow up
+    emplaceText<doc::Text>(true, C->getText().str());
 }
 
 void
diff --git a/src/lib/Gen/adoc/AdocCorpus.cpp b/src/lib/Gen/adoc/AdocCorpus.cpp
@@ -104,8 +104,9 @@ class DocVisitor
     void operator()(doc::Text const& I);
     void operator()(doc::Styled const& I);
     void operator()(doc::TParam const& I);
-    void operator()(doc::Reference const& I);
     void operator()(doc::Throws const& I);
+    void operator()(doc::Reference const& I);
+    void operator()(doc::Related const& I);
 
     std::size_t measureLeftMargin(
         doc::List<doc::Text> const& list);
@@ -307,6 +308,12 @@ operator()(doc::Reference const& I)
         corpus_.getXref(corpus_->get(I.id)), escapeAdoc(I.string));
 }
 
+void
+DocVisitor::
+operator()(doc::Related const& I)
+{
+}
+
 std::size_t
 DocVisitor::
 measureLeftMargin(
@@ -417,6 +424,18 @@ domCreate(
     return s;
 }
 
+static
+dom::Value
+domCreate(
+    const doc::Related& I,
+    const AdocCorpus& corpus)
+{
+    std::string s;
+    DocVisitor visitor(corpus, s);
+    visitor(static_cast<const doc::Related&>(I));
+    return s;
+}
+
 //------------------------------------------------
 
 class DomJavadoc : public dom::LazyObjectImpl
@@ -506,6 +525,7 @@ class DomJavadoc : public dom::LazyObjectImpl
         maybeEmplaceArray(list, "see", ov.sees);
         maybeEmplaceArray(list, "preconditions", ov.preconditions);
         maybeEmplaceArray(list, "postconditions", ov.postconditions);
+        maybeEmplaceArray(list, "related", ov.related);
 
         return dom::Object(std::move(list));
     }
diff --git a/src/lib/Metadata/Javadoc.cpp b/src/lib/Metadata/Javadoc.cpp
@@ -291,6 +291,19 @@ makeOverview(
                 break;
             ov.blocks.push_back(it->get());
         }
+
+        for(const auto& child : it->get()->children)
+        {
+            switch(child->kind)
+            {
+            case doc::Kind::related:
+                ov.related.push_back(static_cast<
+                    doc::Related const*>(child.get()));
+                break;
+            default:
+                break;
+            }
+        }
     }
 
     return ov;
