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);
     });

mrdocs.rnc

@@ -390,7 +390,8 @@ grammar
     BlockNode = (
         Admonition | Brief | Code | Heading | ListItem |
         UnorderedList | Paragraph | Param | Returns | TParam |
-        Throws | See | Precondition | Postcondition | Details)
+        Throws | See | Precondition | Postcondition | Details |
+        Related | Relates)
 
     Admonition = Paragraph
     Brief = element brief { TextNode * }
@@ -417,7 +418,10 @@ grammar
     Postcondition = element post { TextNode * }
     Details = element details { TextNode * }
 
-    TextNode = ( Link | Styled | Text | Reference | Related | Copied )
+    Related = element related { Reference * }
+    Relates = element relates { Reference * }
+
+    TextNode = ( Link | Styled | Text | Reference | Copied )
 
     Link = element link { attribute href { text }, text }
     Styled = (
@@ -427,7 +431,7 @@ grammar
         element italic { text } )
     Text = element text { text }
     Reference = element reference { ID ?, text }
-    Related = element relates { ID ?, text }
+
     Copied =
         element (
             copydoc |

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);