preprocess related symbols

#feat

Author: alandefreitas

include/mrdocs/Metadata/Javadoc.hpp

@@ -123,7 +123,6 @@ enum class NodeKind
     throws,
     details,
     see,
-    related,
     precondition,
     postcondition
 };
@@ -651,52 +650,6 @@ tag_invoke(
     v = dom::LazyObject(I, domCorpus);
 }
 
-/** A reference to a related symbol.
-*/
-struct Related final : Reference
-{
-    static constexpr auto static_kind = NodeKind::related;
-
-    Related(std::string string_ = std::string()) noexcept
-        : Reference(std::move(string_), NodeKind::related)
-    {
-    }
-
-    auto operator<=>(Related const&) const = default;
-    bool operator==(Related const&) const noexcept = default;
-    bool equals(Node const& other) const noexcept override
-    {
-        return Kind == other.Kind &&
-            *this == dynamic_cast<Related const&>(other);
-    }
-};
-
-/** Map the @ref Related to a @ref dom::Object.
- */
-template <class IO>
-void
-tag_invoke(
-    dom::LazyObjectMapTag t,
-    IO& io,
-    Related const& I,
-    DomCorpus const* domCorpus)
-{
-    tag_invoke(t, io, dynamic_cast<Reference const&>(I), domCorpus);
-}
-
-/** Return the @ref Related as a @ref dom::Value object.
- */
-inline
-void
-tag_invoke(
-    dom::ValueFromTag,
-    dom::Value& v,
-    Related const& I,
-    DomCorpus const* domCorpus)
-{
-    v = dom::LazyObject(I, domCorpus);
-}
-
 //------------------------------------------------
 //
 // Block nodes
@@ -1632,8 +1585,6 @@ visit(
         return visitor.template visit<Precondition>();
     case NodeKind::postcondition:
         return visitor.template visit<Postcondition>();
-    case NodeKind::related:
-        return visitor.template visit<Related>();
     default:
         MRDOCS_UNREACHABLE();
     }
@@ -1698,15 +1649,26 @@ struct MRDOCS_DECL
     /// The list of "see also" references.
     std::vector<doc::See> sees;
 
-    /// The list of "related" references.
-    std::vector<SymbolID> related;
-
     /// The list of preconditions.
     std::vector<doc::Precondition> preconditions;
 
     /// The list of postconditions.
     std::vector<doc::Postcondition> postconditions;
 
+    /** The list of "relates" references.
+
+        These references are creates with the
+        \\relates command.
+     */
+    std::vector<doc::Reference> relates;
+
+    /** The list of "related" references.
+
+        These references are the inverse of
+        the \\relates command.
+     */
+    std::vector<doc::Reference> related;
+
     /** Constructor.
     */
     MRDOCS_DECL
@@ -1865,6 +1827,9 @@ tag_invoke(
     io.defer("sees", [&I, domCorpus] {
         return dom::LazyArray(I.sees, domCorpus);
     });
+    io.defer("relates", [&I, domCorpus] {
+        return dom::LazyArray(I.relates, domCorpus);
+    });
     io.defer("related", [&I, domCorpus] {
         return dom::LazyArray(I.related, domCorpus);
     });

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

@@ -46,7 +46,8 @@
 
 [,cols=2]
 |===
-|Name |Description
+| Name
+| Description
 {{#each (filter_by symbol.constants "isRegular" "isSeeBelow")}}
 {{#if (ne kind "enum-constant")}}
 |xref:{{{anchor}}}[`{{>symbol/name . nolink=true}}`]
@@ -66,7 +67,30 @@
 {{/if}}
 {{! Related symbols }}
 {{#if symbol.doc.related}}
-{{>symbol/members-table members=symbol.doc.related title="Related functions"}}
+{{#> markup/dynamic-level-h }}Non-Member Functions{{/markup/dynamic-level-h}}
+[,cols=2]
+|===
+| Name
+| Description
+{{#each symbol.doc.related}}
+| {{> javadoc/reference }}
+| {{> javadoc/inline-brief symbol.doc.brief }}
+{{/each}}
+|===
+
+{{/if}}
+{{! Relates symbols }}
+{{#if symbol.doc.relates }}
+{{#> markup/dynamic-level-h }}Non-Member Of{{/markup/dynamic-level-h}}
+[,cols=2]
+|===
+| Name
+| Description
+{{#each symbol.doc.relates }}
+| {{> javadoc/reference }}
+| {{> javadoc/inline-brief symbol.doc.brief }}
+{{/each}}
+|===
 
 {{/if}}
 {{! Description }}

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

@@ -72,7 +72,7 @@
 {{else}}
 <td>{{>symbol/name . nolink=true}}</td>
 {{/if}}
-<td>{{> javadoc/brief doc.brief }}</td>
+<td>{{> javadoc/inline-brief doc.brief }}</td>
 </tr>
 {{/each}}
 </tbody>
@@ -86,6 +86,44 @@
 
 </div>
 
+{{/if}}
+{{! Related symbols }}
+{{#if symbol.doc.related}}
+<div>
+{{#> markup/dynamic-level-h }}Non-Member Functions{{/markup/dynamic-level-h}}
+<table>
+<thead>
+<tr>
+<th>Name</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+{{#each symbol.doc.related}}
+<tr><td>{{> javadoc/reference }}</td><td>{{> javadoc/inline-brief symbol.doc.brief }}</td></tr>
+{{/each}}
+</tbody>
+</table>
+</div>
+{{/if}}
+{{! Relates symbols }}
+{{#if symbol.doc.relates }}
+<div>
+{{#> markup/dynamic-level-h }}Non-Member Of{{/markup/dynamic-level-h}}
+<table>
+<thead>
+<tr>
+<th>Name</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+{{#each symbol.doc.relates }}
+<tr><td>{{> javadoc/reference }}</td><td>{{> javadoc/inline-brief symbol.doc.brief }}</td></tr>
+{{/each}}
+</tbody>
+</table>
+</div>
 {{/if}}
 {{! Description }}
 {{#if symbol.doc.description}}

src/lib/AST/ParseJavadoc.cpp

@@ -1024,14 +1024,19 @@ visitInlineCommandComment(
     // KRYSTIAN FIXME: these need to be made inline commands in clang
     case CommandTraits::KCI_related:
     case CommandTraits::KCI_relates:
+    // MrDocs doesn't document members inline, so there's no
+    // distinction between "related" and "relatedalso"
+    case CommandTraits::KCI_relatedalso:
+    case CommandTraits::KCI_relatesalso:
+    // Member of is a concept used only in C. MrDocs handles
+    // it as a non-member function is all cases.
+    case CommandTraits::KCI_memberof:
     {
         MRDOCS_CHECK_OR(goodArgCount(1, *C));
         std::string ref = C->getArgText(0).str();
         std::string leftOver = fixReference(ref);
         bool const hasExtra = !leftOver.empty();
-        emplaceText<doc::Related>(
-            C->hasTrailingNewline() && !hasExtra,
-            ref);
+        jd_.relates.emplace_back(std::move(ref));
         if (hasExtra)
         {
             emplaceText<doc::Text>(

src/lib/Gen/xml/CXXTags.hpp

@@ -48,6 +48,8 @@ constexpr auto templateTagName       = "template";
 constexpr auto tparamTagName         = "tparam";
 constexpr auto unionTagName          = "union";
 constexpr auto varTagName            = "variable";
+constexpr auto relatedTagName        = "related";
+constexpr auto relatesTagName        = "relates";
 
 inline dom::String getNameForValue(...)
 {

src/lib/Gen/xml/XMLWriter.cpp

@@ -733,6 +733,18 @@ writeJavadoc(
     writeNodes(javadoc->sees);
     writeNodes(javadoc->preconditions);
     writeNodes(javadoc->postconditions);
+    if (!javadoc->relates.empty())
+    {
+        tags_.open(relatesTagName);
+        writeNodes(javadoc->relates);
+        tags_.close(relatesTagName);
+    }
+    if (!javadoc->related.empty())
+    {
+        tags_.open(relatedTagName);
+        writeNodes(javadoc->related);
+        tags_.close(relatedTagName);
+    }
     tags_.close(javadocTagName);
 }
 
@@ -788,9 +800,6 @@ writeNode(doc::Node const& node)
     case doc::NodeKind::copied:
         writeCopied(dynamic_cast<doc::Copied const&>(node));
         break;
-    case doc::NodeKind::related:
-        writeRelated(dynamic_cast<doc::Related const&>(node));
-        break;
     case doc::NodeKind::throws:
         writeThrows(dynamic_cast<doc::Throws const&>(node));
         break;
@@ -844,16 +853,6 @@ writeCopied(
         });
 }
 
-void
-XMLWriter::
-writeRelated(
-    doc::Related const& node)
-{
-    tags_.write("relates", node.string, {
-        { node.id }
-        });
-}
-
 void
 XMLWriter::
 writeLink(

src/lib/Gen/xml/XMLWriter.hpp

@@ -89,7 +89,6 @@ class XMLWriter
     void writeTParam(doc::TParam const& node);
     void writeReference(doc::Reference const& node);
     void writeCopied(doc::Copied const& node);
-    void writeRelated(doc::Related const& node);
     void writeThrows(doc::Throws const& node);
     void writeSee(doc::See const& node, llvm::StringRef tag = "");
     void writePrecondition(doc::Precondition const& node);

src/lib/Metadata/Finalizers/JavadocFinalizer.cpp

@@ -138,14 +138,6 @@ finalize(doc::Reference& ref, bool const emitWarning)
         // returns a non-const reference.
         auto& res = const_cast<Info&>(resRef->get());
         ref.id = res.id;
-        if(ref.Kind == doc::NodeKind::related)
-        {
-            if(! res.javadoc)
-                res.javadoc.emplace();
-            auto& related = res.javadoc->related;
-            if(std::ranges::find(related, current_context_->id) == related.end())
-                related.emplace_back(current_context_->id);
-        }
     }
     else if (
         emitWarning &&
@@ -180,8 +172,7 @@ finalize(doc::Node& node)
             finalize(N.children);
         }
 
-        if constexpr(std::same_as<NodeTy, doc::Reference> ||
-            std::same_as<NodeTy, doc::Related>)
+        if constexpr(std::same_as<NodeTy, doc::Reference>)
         {
             finalize(dynamic_cast<doc::Reference&>(N), true);
         }
@@ -205,13 +196,62 @@ finalize(Javadoc& javadoc)
     finalize(javadoc.sees);
     finalize(javadoc.preconditions);
     finalize(javadoc.postconditions);
+    setRelateIds(javadoc);
     copyBriefAndDetails(javadoc);
     setAutoBrief(javadoc);
     removeTempTextNodes(javadoc);
     trimBlocks(javadoc);
     unindentCodeBlocks(javadoc);
 }
 
+void
+JavadocFinalizer::
+setRelateIds(Javadoc& javadoc)
+{
+    MRDOCS_CHECK_OR(!javadoc.relates.empty());
+
+    Info const* currentPtr = corpus_.find(current_context_->id);
+    MRDOCS_ASSERT(currentPtr);
+    Info const current = *currentPtr;
+
+    if (!current.isFunction())
+    {
+        this->warn(
+            "{}: `@relates` only allowed for functions",
+            corpus_.Corpus::qualifiedName(current));
+        javadoc.relates.clear();
+        return;
+    }
+
+    for (doc::Reference& ref: javadoc.relates)
+    {
+        finalize(ref, true);
+        Info* relatedPtr = corpus_.find(ref.id);
+        MRDOCS_CHECK_OR_CONTINUE(relatedPtr);
+        Info& related = *relatedPtr;
+        if (!related.javadoc)
+        {
+            related.javadoc.emplace();
+        }
+        if (std::ranges::none_of(
+                related.javadoc->related,
+                [this](doc::Reference const& otherRef) {
+            return otherRef.id == current_context_->id;
+        }))
+        {
+            std::string currentName = corpus_.Corpus::qualifiedName(current);
+            doc::Reference relatedRef(std::move(currentName));
+            relatedRef.id = current_context_->id;
+            related.javadoc->related.push_back(std::move(relatedRef));
+        }
+    }
+
+    // Erase anything in the javadoc without a valid id
+    std::erase_if(javadoc.relates, [](doc::Reference const& ref) {
+        return !ref.id;
+    });
+}
+
 void
 JavadocFinalizer::
 copyBriefAndDetails(Javadoc& javadoc)
@@ -722,7 +762,7 @@ removeTempTextNodes(doc::Block& block)
     std::erase_if(block.children, [](Polymorphic<doc::Text> const& child) {
         return is_one_of(
             child->Kind,
-            { doc::NodeKind::copied, doc::NodeKind::related });
+            { doc::NodeKind::copied });
     });
 }