auto-function-metadata option

#feat

Author: alandefreitas

docs/mrdocs.schema.json

@@ -17,6 +17,16 @@
       "title": "Use the first line of the comment as the brief",
       "type": "boolean"
     },
+    "auto-function-metadata": {
+      "default": true,
+      "description": "When set to `true`, MrDocs automatically provides documentation for special functions, such as constructors, destructors, and operators. It also provides documentation for missing documentation metadata, such as known types.",
+      "enum": [
+        true,
+        false
+      ],
+      "title": "Automatically provide missing documentation for special functions and trivial metadata",
+      "type": "boolean"
+    },
     "auto-relates": {
       "default": true,
       "description": "When set to `true`, MrDocs automatically finds non-member functions that are related to the current class.",

include/mrdocs/Metadata/Info/Function.hpp

@@ -70,6 +70,13 @@ getSafeOperatorName(
     OperatorKind kind,
     bool include_keyword = false) noexcept;
 
+/** Return the human-readable name of the operator
+ */
+std::optional<std::string_view>
+getOperatorReadableName(
+    OperatorKind kind,
+    int nParams);
+
 /** Function classifications */
 enum class FunctionClass
 {

include/mrdocs/Metadata/Javadoc.hpp

@@ -119,7 +119,7 @@ enum class NodeKind
     styled,
     tparam,
     reference,
-    copied,
+    copy_details,
     throws,
     details,
     see,
@@ -373,7 +373,8 @@ struct Text : Node
     {
     }
 
-    bool isBlock() const noexcept final
+    bool
+    isBlock() const noexcept final
     {
         return false;
     }
@@ -600,26 +601,21 @@ tag_invoke(
 
 /** Documentation copied from another symbol.
 */
-struct Copied final : Reference
+struct CopyDetails final : Reference
 {
-    Parts parts;
-
-    static constexpr auto static_kind = NodeKind::copied;
+    static constexpr auto static_kind = NodeKind::copy_details;
 
-    Copied(
-        std::string string_ = std::string(),
-        Parts parts_ = Parts::all) noexcept
-        : Reference(std::move(string_), NodeKind::copied)
-        , parts(parts_)
+    CopyDetails(std::string string_ = std::string()) noexcept
+        : Reference(std::move(string_), NodeKind::copy_details)
     {
     }
 
-    auto operator<=>(Copied const&) const = default;
-    bool operator==(Copied const&) const noexcept = default;
+    auto operator<=>(CopyDetails const&) const = default;
+    bool operator==(CopyDetails const&) const noexcept = default;
     bool equals(Node const& other) const noexcept override
     {
         return Kind == other.Kind &&
-            *this == dynamic_cast<Copied const&>(other);
+            *this == dynamic_cast<CopyDetails const&>(other);
     }
 };
 
@@ -630,11 +626,10 @@ void
 tag_invoke(
     dom::LazyObjectMapTag t,
     IO& io,
-    Copied const& I,
+    CopyDetails const& I,
     DomCorpus const* domCorpus)
 {
     tag_invoke(t, io, dynamic_cast<Reference const&>(I), domCorpus);
-    io.map("parts", I.parts);
 }
 
 /** Return the @ref Copied as a @ref dom::Value object.
@@ -644,7 +639,7 @@ void
 tag_invoke(
     dom::ValueFromTag,
     dom::Value& v,
-    Copied const& I,
+    CopyDetails const& I,
     DomCorpus const* domCorpus)
 {
     v = dom::LazyObject(I, domCorpus);
@@ -825,10 +820,10 @@ struct Paragraph : Block
 {
     static constexpr auto static_kind = NodeKind::paragraph;
 
-    Paragraph() noexcept
-        : Block(NodeKind::paragraph)
-    {
-    }
+    Paragraph() noexcept : Block(NodeKind::paragraph) {}
+
+    virtual Paragraph&
+    operator=(std::string_view str);
 
     auto operator<=>(Paragraph const&) const = default;
 
@@ -881,11 +876,30 @@ struct Brief final : Paragraph
 {
     static constexpr NodeKind static_kind = NodeKind::brief;
 
+    std::vector<std::string> copiedFrom;
+
     Brief() noexcept
         : Paragraph(NodeKind::brief)
     {
     }
 
+    explicit
+    Brief(std::string_view const text)
+        : Brief()
+    {
+        operator=(text);
+    }
+
+    Brief&
+    operator=(Brief const& other) = default;
+
+    Brief&
+    operator=(std::string_view const text) override
+    {
+        Paragraph::operator=(text);
+        return *this;
+    }
+
     auto operator<=>(Brief const&) const = default;
 
     bool equals(Node const& other) const noexcept override
@@ -1228,6 +1242,30 @@ struct Param final : Paragraph
     {
     }
 
+    explicit
+    Param(
+        std::string_view const name,
+        std::string_view const text)
+    : Param()
+    {
+        this->name = name;
+        this->operator=(text);
+    }
+
+    explicit
+    Param(Paragraph const& other)
+        : Param()
+    {
+        children = other.children;
+    }
+
+    Param&
+    operator=(std::string_view const text) override
+    {
+        Paragraph::operator=(text);
+        return *this;
+    }
+
     auto operator<=>(Param const&) const = default;
 
     bool operator==(Param const&)
@@ -1279,6 +1317,27 @@ struct Returns final : Paragraph
     {
     }
 
+    explicit
+    Returns(std::string_view const text)
+        : Returns()
+    {
+        operator=(text);
+    }
+
+    explicit
+    Returns(Paragraph const& other)
+        : Returns()
+    {
+        children = other.children;
+    }
+
+    Returns&
+    operator=(std::string_view const text) override
+    {
+        Paragraph::operator=(text);
+        return *this;
+    }
+
     auto operator<=>(Returns const&) const = default;
 
     bool operator==(Returns const&)
@@ -1561,8 +1620,8 @@ visit(
         return visitor.template visit<Link>();
     case NodeKind::reference:
         return visitor.template visit<Reference>();
-    case NodeKind::copied:
-        return visitor.template visit<Copied>();
+    case NodeKind::copy_details:
+        return visitor.template visit<CopyDetails>();
     case NodeKind::list_item:
         return visitor.template visit<ListItem>();
     case NodeKind::unordered_list:
@@ -1698,14 +1757,6 @@ struct MRDOCS_DECL
             postconditions.empty();
     }
 
-    /** Return the brief, or nullptr if there is none.
-    */
-    doc::Paragraph const*
-    getBrief(Corpus const& corpus) const noexcept;
-
-    std::vector<Polymorphic<doc::Block>> const&
-    getDescription(Corpus const& corpus) const noexcept;
-
     /** Return the list of top level blocks.
     */
     std::vector<Polymorphic<doc::Block>> const&

include/mrdocs/Metadata/Specifiers.hpp

@@ -180,6 +180,18 @@ tag_invoke(
     v = static_cast<std::underlying_type_t<OperatorKind>>(kind);
 }
 
+/** Determines whether the operator is potentially unary.
+ */
+MRDOCS_DECL
+bool
+isUnaryOperator(OperatorKind kind) noexcept;
+
+/** Determines whether the operator is potentially binary.
+ */
+MRDOCS_DECL
+bool
+isBinaryOperator(OperatorKind kind) noexcept;
+
 /** Reference type kinds
 */
 enum class ReferenceKind

include/mrdocs/Support/Algorithm.hpp

@@ -25,7 +25,7 @@ namespace clang::mrdocs {
 template <std::ranges::range Range, class El>
 requires std::equality_comparable_with<El, std::ranges::range_value_t<Range>>
 bool
-contains(Range const& range, El const& el)
+contains(Range&& range, El const& el)
 {
     return std::find(
         std::ranges::begin(range),

src/lib/AST/ParseJavadoc.cpp

@@ -992,10 +992,30 @@ visitInlineCommandComment(
         std::string ref = C->getArgText(0).str();
         std::string leftOver = fixReference(ref);
         bool const hasExtra = !leftOver.empty();
-        emplaceText<doc::Copied>(
-            C->hasTrailingNewline() && !hasExtra,
-            ref,
-            convertCopydoc(ID));
+        doc::Parts const parts = convertCopydoc(ID);
+        bool const copyBrief = parts == doc::Parts::brief || parts == doc::Parts::all;
+        bool const copyDetails = parts == doc::Parts::description || parts == doc::Parts::all;
+        MRDOCS_ASSERT(copyBrief || copyDetails);
+        if (copyBrief)
+        {
+            // The brief is metadata associated with the javadoc
+            if (!jd_.brief)
+            {
+                jd_.brief.emplace();
+            }
+            if (!contains(jd_.brief->copiedFrom, ref))
+            {
+                jd_.brief->copiedFrom.emplace_back(ref);
+            }
+        }
+        if (copyDetails)
+        {
+            // The details are in the main body of the javadoc
+            // and are replaced at the same position as the command
+            emplaceText<doc::CopyDetails>(
+                C->hasTrailingNewline() && !hasExtra,
+                ref);
+        }
         if (hasExtra)
         {
             emplaceText<doc::Text>(

src/lib/Gen/xml/XMLWriter.cpp

@@ -797,8 +797,8 @@ writeNode(doc::Node const& node)
     case doc::NodeKind::reference:
         writeReference(dynamic_cast<doc::Reference const&>(node));
         break;
-    case doc::NodeKind::copied:
-        writeCopied(dynamic_cast<doc::Copied const&>(node));
+    case doc::NodeKind::copy_details:
+        writeCopied(dynamic_cast<doc::CopyDetails const&>(node));
         break;
     case doc::NodeKind::throws:
         writeThrows(dynamic_cast<doc::Throws const&>(node));
@@ -831,23 +831,9 @@ writeReference(
 void
 XMLWriter::
 writeCopied(
-    doc::Copied const& node)
+    doc::CopyDetails const& node)
 {
-    std::string_view tag_name;
-    switch(node.parts)
-    {
-    case doc::Parts::all:
-        tag_name = "copydoc";
-        break;
-    case doc::Parts::brief:
-        tag_name = "copybrief";
-        break;
-    case doc::Parts::description:
-        tag_name = "copydetails";
-        break;
-    default:
-        MRDOCS_UNREACHABLE();
-    }
+    std::string_view const tag_name = "copydetails";
     tags_.write(tag_name, node.string, {
         { node.id }
         });

src/lib/Gen/xml/XMLWriter.hpp

@@ -88,7 +88,7 @@ class XMLWriter
     void writeText(doc::Text const& node);
     void writeTParam(doc::TParam const& node);
     void writeReference(doc::Reference const& node);
-    void writeCopied(doc::Copied const& node);
+    void writeCopied(doc::CopyDetails 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/Lib/ConfigOptions.json

@@ -177,6 +177,13 @@
         "details": "When set to `true`, MrDocs automatically finds non-member functions that are related to the current class.",
         "type": "bool",
         "default": true
+      },
+      {
+        "name": "auto-function-metadata",
+        "brief": "Automatically provide missing documentation for special functions and trivial metadata",
+        "details": "When set to `true`, MrDocs automatically provides documentation for special functions, such as constructors, destructors, and operators. It also provides documentation for missing documentation metadata, such as known types.",
+        "type": "bool",
+        "default": true
       }
     ]
   },