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::copy_details;
 
-    static constexpr auto static_kind = NodeKind::copied;
-
-    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,11 @@ 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 +877,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
@@ -939,8 +954,12 @@ struct Admonition final : Paragraph
     {
     }
 
+    using Paragraph::operator=;
+
     auto operator<=>(Admonition const&) const = default;
+
     bool operator==(Admonition const&) const noexcept = default;
+
     bool equals(Node const& other) const noexcept override
     {
         return Kind == other.Kind &&
@@ -989,6 +1008,7 @@ struct Code final : Paragraph
     {
     }
 
+    using Paragraph::operator=;
     auto operator<=>(Code const&) const = default;
     bool operator==(Code const&) const noexcept = default;
     bool equals(Node const& other) const noexcept override
@@ -1034,6 +1054,8 @@ struct ListItem final : Paragraph
         : Paragraph(static_kind)
     {}
 
+    using Paragraph::operator=;
+
     auto operator<=>(ListItem const&) const = default;
     bool
     operator==(ListItem const&) const noexcept = default;
@@ -1093,6 +1115,8 @@ struct UnorderedList final : Paragraph
     {
     }
 
+    using Paragraph::operator=;
+
     auto operator<=>(UnorderedList const& other) const {
         if (auto const cmp = items.size() <=> other.items.size();
             !std::is_eq(cmp))
@@ -1169,6 +1193,8 @@ struct See final : Paragraph
     {
     }
 
+    using Paragraph::operator=;
+
     auto operator<=>(See const&) const = default;
 
     bool operator==(See const&)
@@ -1228,6 +1254,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 +1329,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&)
@@ -1330,6 +1401,8 @@ struct TParam final : Paragraph
     {
     }
 
+    using Paragraph::operator=;
+
     auto operator<=>(TParam const&) const = default;
     bool operator==(TParam const&) const noexcept = default;
     bool equals(Node const& other) const noexcept override
@@ -1384,6 +1457,8 @@ struct Throws final : Paragraph
     {
     }
 
+    using Paragraph::operator=;
+
     auto operator<=>(Throws const&) const = default;
 
     bool operator==(Throws const&)
@@ -1435,6 +1510,8 @@ struct Precondition final : Paragraph
     {
     }
 
+    using Paragraph::operator=;
+
     auto operator<=>(Precondition const&) const = default;
 
     bool operator==(Precondition const&)
@@ -1485,6 +1562,8 @@ struct Postcondition : Paragraph
     {
     }
 
+    using Paragraph::operator=;
+
     auto operator<=>(Postcondition const&) const = default;
 
     bool operator==(Postcondition const&)
@@ -1561,8 +1640,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 +1777,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/AST/ParseRef.cpp

@@ -854,9 +854,9 @@ class RefParser
     bool
     parseDeclarationSpecifiers(Polymorphic<TypeInfo>& dest)
     {
-        static constexpr std::string_view typeQualifiers[] = {
-            "const", "volatile"
-        };
+        //static constexpr std::string_view typeQualifiers[] = {
+        //    "const", "volatile"
+        //};
         static constexpr std::string_view typeModifiers[] = {
             "long", "short", "signed", "unsigned"
         };