feat: support @relates

Author: sdkrystian

include/mrdocs/Metadata/Javadoc.hpp

@@ -127,6 +127,7 @@ enum class Kind
     throws,
     details,
     see,
+    related,
     precondition,
     postcondition
 };
@@ -365,6 +366,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
@@ -841,6 +861,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)...);
     }
@@ -908,6 +930,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();
     }
@@ -942,6 +966,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;

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

@@ -219,3 +219,13 @@
 {{/each}}
 
 {{/if}}
+{{! Related }}
+{{#if symbol.doc.related}}
+{{#> markup/dynamic-level-h }}Related{{/markup/dynamic-level-h}}
+
+{{#each symbol.doc.related}}
+{{{.}}}
+
+{{/each}}
+
+{{/if}}

src/lib/AST/ParseJavadoc.cpp

@@ -1120,6 +1120,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;

src/lib/Gen/hbs/HandlebarsCorpus.cpp

@@ -99,6 +99,14 @@ domCreate(
     return corpus.toStringFn(corpus, I);
 }
 
+dom::Value
+domCreate(
+    const doc::Related& I,
+    const HandlebarsCorpus& corpus)
+{
+    return corpus.toStringFn(corpus, I);
+}
+
 dom::Value
 domCreate(
     const doc::Precondition& I,
@@ -258,6 +266,7 @@ getJavadoc(Javadoc const& jd) const
     emplaceObjectArray("see", ov.sees);
     emplaceObjectArray("preconditions", ov.preconditions);
     emplaceObjectArray("postconditions", ov.postconditions);
+    emplaceObjectArray("related", ov.related);
     return dom::Object(std::move(objKeyValues));
 }
 

src/lib/Metadata/Javadoc.cpp

@@ -263,6 +263,8 @@ makeOverview(
         {
         case doc::Kind::brief:
             break;
+        case doc::Kind::related:
+            break;
         case doc::Kind::returns:
             ov.returns = static_cast<
                 doc::Returns const*>(it->get());
@@ -298,6 +300,19 @@ makeOverview(
             }
             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;