preprocess javadoc metadata

#perf

Author: alandefreitas

include/mrdocs/Metadata/Javadoc.hpp

@@ -731,13 +731,13 @@ struct Param final : Paragraph
 
     auto operator<=>(Param const&) const = default;
 
-    bool operator==(const Param&)
+    bool operator==(Param const&)
         const noexcept = default;
 
-    bool equals(const Node& other) const noexcept override
+    bool equals(Node const& other) const noexcept override
     {
         return Kind == other.Kind &&
-            *this == dynamic_cast<const Param&>(other);
+            *this == dynamic_cast<Param const&>(other);
     }
 };
 
@@ -1008,19 +1008,6 @@ void traverse(
             std::forward<Args>(args)...);
 }
 
-struct Overview
-{
-    std::shared_ptr<Paragraph> brief = nullptr;
-    std::vector<Block const*> blocks;
-    Returns const* returns = nullptr;
-    std::vector<Param const*> params;
-    std::vector<TParam const*> tparams;
-    std::vector<Throws const*> exceptions;
-    std::vector<See const*> sees;
-    std::vector<Precondition const*> preconditions;
-    std::vector<Postcondition const*> postconditions;
-};
-
 MRDOCS_DECL
 dom::String
 toString(Style style) noexcept;
@@ -1036,7 +1023,41 @@ class Corpus;
 struct MRDOCS_DECL
     Javadoc
 {
-    std::vector<Polymorphic<doc::Block>> blocks_;
+    /// The list of text blocks.
+    std::vector<Polymorphic<doc::Block>> blocks;
+
+    // ----------------------
+    // Symbol Metadata
+
+    /// A brief description of the symbol.
+    std::optional<doc::Brief> brief;
+
+    /** The list of return type descriptions.
+
+        Multiple return descriptions are allowed.
+
+        The results are concatenated in the order
+        they appear in the source code.
+     */
+    std::vector<doc::Returns> returns;
+
+    /// The list of parameters.
+    std::vector<doc::Param> params;
+
+    /// The list of template parameters.
+    std::vector<doc::TParam> tparams;
+
+    /// The list of exceptions.
+    std::vector<doc::Throws> exceptions;
+
+    /// The list of "see also" references.
+    std::vector<doc::See> sees;
+
+    /// The list of preconditions.
+    std::vector<doc::Precondition> preconditions;
+
+    /// The list of postconditions.
+    std::vector<doc::Postcondition> postconditions;
 
     /** Constructor.
     */
@@ -1054,7 +1075,16 @@ struct MRDOCS_DECL
     bool
     empty() const noexcept
     {
-        return blocks_.empty();
+        return
+            blocks.empty() &&
+            !brief &&
+            returns.empty() &&
+            params.empty() &&
+            tparams.empty() &&
+            exceptions.empty() &&
+            sees.empty() &&
+            preconditions.empty() &&
+            postconditions.empty();
     }
 
     /** Return the brief, or nullptr if there is none.
@@ -1070,15 +1100,15 @@ struct MRDOCS_DECL
     std::vector<Polymorphic<doc::Block>> const&
     getBlocks() const noexcept
     {
-        return blocks_;
+        return blocks;
     }
 
     // VFALCO This is unfortunately necessary for
     //        the deserialization from bitcode...
     std::vector<Polymorphic<doc::Block>>&
     getBlocks() noexcept
     {
-        return blocks_;
+        return blocks;
     }
 
     //--------------------------------------------
@@ -1091,14 +1121,14 @@ struct MRDOCS_DECL
     */
     /** @{ */
     auto operator<=>(Javadoc const& other) const noexcept {
-        if (auto const cmp = blocks_.size() <=> other.blocks_.size();
+        if (auto const cmp = blocks.size() <=> other.blocks.size();
             !std::is_eq(cmp))
         {
             return cmp;
         }
-        for (std::size_t i = 0; i < blocks_.size(); ++i)
+        for (std::size_t i = 0; i < blocks.size(); ++i)
         {
-            if (auto cmp = CompareDerived(blocks_[i], other.blocks_[i]);
+            if (auto cmp = CompareDerived(blocks[i], other.blocks[i]);
                 !std::is_eq(cmp))
             {
                 return cmp;
@@ -1110,22 +1140,6 @@ struct MRDOCS_DECL
     bool operator!=(Javadoc const&) const noexcept;
     /* @} */
 
-    /** Return an overview of the javadoc.
-
-        The Javadoc is stored as a list of blocks,
-        in the order of appearance in the corresponding
-        source code. This function separates elements
-        according to their semantic content and returns
-        the result as a set of collated lists and
-        individual elements.
-
-        Ownership of the nodes is not transferred;
-        the returend overview is invalidated if the
-        javadoc object is destroyed.
-    */
-    doc::Overview
-    makeOverview(const Corpus& corpus) const;
-
     //--------------------------------------------
 
     /** Attempt to append a block.

include/mrdocs/Support/Concepts.hpp

@@ -38,6 +38,13 @@ concept polymorphic_storage_for = requires(T const& t)
     { t.operator->() } -> std::convertible_to<Base const*>;
 };
 
+template <class T>
+concept dereferenceable = requires(T const& t)
+{
+    { static_cast<bool>(t) };
+    { *t };
+};
+
 } // namespace clang::mrdocs
 
 

include/mrdocs/Support/ScopeExit.hpp

@@ -49,8 +49,9 @@ class ScopeExitRestore {
         : prev_(ref), ref_(ref)
     {}
 
+    template <std::convertible_to<T> T2>
     explicit
-    ScopeExitRestore(T& ref, T next)
+    ScopeExitRestore(T& ref, T2 next)
         : prev_(ref), ref_(ref)
     {
         ref_ = next;
@@ -72,8 +73,8 @@ class ScopeExitRestore {
 template <class T>
 ScopeExitRestore(T&) -> ScopeExitRestore<T>;
 
-template <class T>
-ScopeExitRestore(T&, T) -> ScopeExitRestore<T>;
+template <class T, std::convertible_to<T> T2>
+ScopeExitRestore(T&, T2) -> ScopeExitRestore<T>;
 
 }
 

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

@@ -99,6 +99,7 @@
 {{#each symbol.doc.exceptions}}
 | `{{exception}}`
 | {{{description}}}
+
 {{/each}}
 |===
 
@@ -114,6 +115,7 @@
 {{#each allExceptions as |exception|}}
 | `{{exception.exception}}`
 | {{{exception.description}}}
+
 {{/each}}
 |===
 
@@ -124,7 +126,13 @@
 {{#if symbol.doc.returns}}
 {{#> markup/dynamic-level-h }}Return Value{{/markup/dynamic-level-h}}
 
-{{{symbol.doc.returns}}}
+{{#if (eq (size symbol.doc.returns) 1)}}
+{{{symbol.doc.returns.[0]}}}
+{{else}}
+{{#each symbol.doc.returns}}
+* {{{.}}}
+{{/each}}
+{{/if}}
 
 {{/if}}
 {{! Template Parameters }}
@@ -138,6 +146,7 @@
 {{#each symbol.doc.tparams}}
 | *{{name}}*
 | {{{description}}}
+
 {{/each}}
 |===
 
@@ -153,6 +162,7 @@
 {{#each allTParams as |param|}}
 | *{{param.name}}*
 | {{{param.description}}}
+
 {{/each}}
 |===
 
@@ -170,6 +180,7 @@
 {{#each symbol.doc.params}}
 | *{{name}}*{{#if direction}} [{{direction}}]{{/if}}
 | {{{description}}}
+
 {{/each}}
 |===
 
@@ -185,6 +196,7 @@
 {{#each allParams as |param|}}
 | *{{param.name}}*
 | {{{param.description}}}
+
 {{/each}}
 |===
 

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

@@ -167,7 +167,15 @@
 {{#if symbol.doc.returns}}
 <div>
 {{#> markup/dynamic-level-h level=2 }}Return Value{{/markup/dynamic-level-h}}
-{{{symbol.doc.returns}}}
+{{#if (eq (size symbol.doc.returns) 1)}}
+{{{symbol.doc.returns.[0]}}}
+{{else}}
+<ul>
+{{#each symbol.doc.returns}}
+<li>{{{.}}}</li>
+{{/each}}
+</ul>
+{{/if}}
 </div>
 {{/if}}
 {{! Template Parameters }}