chore: generators render javadocs

Author: vinniefalco

include/mrdox/Metadata/DomMetadata.hpp

@@ -22,6 +22,10 @@ namespace clang {
 namespace mrdox {
 
 /** Front-end factory for producing Dom nodes.
+
+    A @ref Generator subclasses this object and
+    then uses it to create the Dom nodes used for
+    rendering in template engines.
 */
 class MRDOX_DECL
     DomCorpus
@@ -31,24 +35,65 @@ class MRDOX_DECL
     std::unique_ptr<Impl> impl_;
 
 public:
+    /** The Corpus associated with the Dom.
+    */
     Corpus const& corpus;
 
+    /** Destructor.
+
+        Ownership of the corpus is not released.
+    */
     ~DomCorpus();
 
+    /** Constructor.
+
+        @param corpus The Corpus whose metadata to use.
+    */
     explicit
-    DomCorpus(Corpus const&);
+    DomCorpus(Corpus const& corpus);
+
+    /** Return a Dom object representing the given symbol.
+
+        @return A value containing the symbol contents.
 
+        @param id The id of the symbol to return.
+    */
     dom::Object
     get(SymbolID const& id) const;
 
+    /** Return a Dom object representing the given symbol.
+
+        @return A value containing the symbol contents.
+
+        @param I The metadata for the symbol.
+    */
     dom::Object
     get(Info const& I) const;
 
-    /** Return the object for id, or null if id is zero.
+    /** Return a Dom object representing the given symbol.
+
+        When `id` is zero, this function returns null.
+
+        @return A value containing the symbol
+        contents, or null if `id` equals zero.
+
+        @param id The id of the symbol to return.
     */
     dom::Value
     getOptional(
         SymbolID const& id) const;
+
+    /** Return a Dom value representing the Javadoc.
+
+        The default implementation returns null. A
+        @ref Generator should override this member
+        and return a value that has suitable strings
+        in the generator's output format.
+    */
+    virtual
+    dom::Value
+    getJavadoc(
+        Javadoc const& jd) const;
 };
 
 } // mrdox

source/-adoc/DocVisitor.hpp source/-adoc/AdocCorpus.cpp

@@ -4,62 +4,22 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2023 Vinnie Falco ([email protected])
+// Copyright (c) 2023 Krystian Stasiowski ([email protected])
 //
 // Official repository: https://github.com/cppalliance/mrdox
 //
 
-#ifndef MRDOX_TOOL_ADOC_DOCVISITOR_HPP
-#define MRDOX_TOOL_ADOC_DOCVISITOR_HPP
-
-#include <mrdox/Platform.hpp>
-#include <mrdox/Metadata/Javadoc.hpp>
+#include "AdocCorpus.hpp"
 #include <mrdox/Support/RangeFor.hpp>
+#include <mrdox/Support/String.hpp>
 #include <fmt/format.h>
+#include <iterator>
 
 namespace clang {
 namespace mrdox {
 namespace adoc {
 
-inline
-std::string_view
-ltrim(std::string_view s)
-{
-    auto it = s.begin();
-    for (;; ++it)
-    {
-        if (it == s.end())
-            return {};
-        if (!isspace(*it))
-            break;
-    }
-    return s.substr(it - s.begin());
-}
-
-inline
-std::string_view
-rtrim(std::string_view s)
-{
-    auto it = s.end() - 1;
-    for (; it > s.begin() && isspace(*it); --it);
-    return s.substr(0, it - s.begin());
-}
-
-inline
-std::string_view
-trim(std::string_view s)
-{
-    auto left = s.begin();
-    for (;; ++left)
-    {
-        if (left == s.end())
-            return {};
-        if (!isspace(*left))
-            break;
-    }
-    auto right = s.end() - 1;
-    for (; right > left && isspace(*right); --right);
-    return std::string_view(&*left, right - left + 1);
-}
+namespace {
 
 class DocVisitor
 {
@@ -87,7 +47,6 @@ class DocVisitor
         doc::List<doc::Text> const& list);
 };
 
-inline
 DocVisitor::
 DocVisitor(
     std::string& dest) noexcept
@@ -96,7 +55,6 @@ DocVisitor(
 {
 }
 
-inline
 void
 DocVisitor::
 operator()(
@@ -106,7 +64,6 @@ operator()(
         doc::visit(*block, *this);
 }
 
-inline
 void
 DocVisitor::
 operator()(
@@ -115,7 +72,6 @@ operator()(
     //dest_ += I.string;
 }
 
-inline
 void
 DocVisitor::
 operator()(
@@ -149,7 +105,6 @@ operator()(
     dest_ += "----\n";
 }
 
-inline
 void
 DocVisitor::
 operator()(
@@ -159,7 +114,6 @@ operator()(
 }
 
 //void operator()(doc::Brief const& I)
-inline
 void
 DocVisitor::
 operator()(
@@ -182,7 +136,6 @@ operator()(
     dest_.push_back('\n');
 }
 
-inline
 void
 DocVisitor::
 operator()(
@@ -195,7 +148,6 @@ operator()(
     dest_.push_back(']');
 }
 
-inline
 void
 DocVisitor::
 operator()(
@@ -219,23 +171,20 @@ operator()(
     dest_.push_back('\n');
 }
 
-inline
 void
 DocVisitor::
 operator()(doc::Param const& I)
 {
     //dest_ += I.string;
 }
 
-inline
 void
 DocVisitor::
 operator()(doc::Returns const& I)
 {
     //dest_ += I.string;
 }
 
-inline
 void
 DocVisitor::
 operator()(doc::Text const& I)
@@ -246,7 +195,6 @@ operator()(doc::Text const& I)
     dest_.append(s);
 }
 
-inline
 void
 DocVisitor::
 operator()(doc::Styled const& I)
@@ -273,15 +221,13 @@ operator()(doc::Styled const& I)
     }
 }
 
-inline
 void
 DocVisitor::
 operator()(doc::TParam const& I)
 {
     //dest_ += I.string;
 }
 
-inline
 std::size_t
 DocVisitor::
 measureLeftMargin(
@@ -302,8 +248,61 @@ measureLeftMargin(
     return n;
 }
 
+//------------------------------------------------
+
+class DomJavadoc : public dom::LazyObjectImpl
+{
+    Javadoc const& jd_;
+
+public:
+    DomJavadoc(
+        Javadoc const& jd) noexcept
+        : jd_(jd)
+    {
+    }
+
+    dom::Object
+    construct() const override
+    {
+        entries_type list;
+        list.reserve(2);
+
+        // brief
+        if(auto brief = jd_.getBrief())
+        {
+            std::string s;
+            DocVisitor visitor(s);
+            s.clear();
+            visitor(*brief);
+            if(! s.empty())
+                list.emplace_back("brief", std::move(s));
+        }
+
+        // description
+        if(! jd_.getBlocks().empty())
+        {
+            std::string s;
+            DocVisitor visitor(s);
+            s.clear();
+            visitor(jd_.getBlocks());
+            if(! s.empty())
+                list.emplace_back("description", std::move(s));
+        }
+
+        return dom::Object(std::move(list));
+    }
+};
+
+} // (anon)
+
+dom::Value
+AdocCorpus::
+getJavadoc(
+    Javadoc const& jd) const
+{
+    return dom::newObject<DomJavadoc>(jd);
+}
+
 } // adoc
 } // mrdox
 } // clang
-
-#endif

source/-adoc/AdocCorpus.hpp

@@ -0,0 +1,40 @@
+//
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2023 Vinnie Falco ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdox
+//
+
+#ifndef MRDOX_TOOL_ADOC_ADOCCORPUS_HPP
+#define MRDOX_TOOL_ADOC_ADOCCORPUS_HPP
+
+#include <mrdox/Platform.hpp>
+#include <mrdox/Metadata/DomMetadata.hpp>
+
+namespace clang {
+namespace mrdox {
+namespace adoc {
+
+class AdocCorpus : public DomCorpus
+{
+public:
+    explicit
+    AdocCorpus(
+        Corpus const& corpus)
+        : DomCorpus(corpus)
+    {
+    }
+
+    dom::Value
+    getJavadoc(
+        Javadoc const& jd) const override;
+};
+
+} // adoc
+} // mrdox
+} // clang
+
+#endif

source/-adoc/AdocGenerator.cpp

@@ -9,6 +9,7 @@
 // Official repository: https://github.com/cppalliance/mrdox
 //
 
+#include "AdocCorpus.hpp"
 #include "AdocGenerator.hpp"
 #include "Builder.hpp"
 #include "MultiPageVisitor.hpp"
@@ -64,7 +65,7 @@ build(
     if(! corpus.config.multiPage)
         return Generator::build(outputPath, corpus);
 
-    DomCorpus domCorpus(corpus);
+    AdocCorpus domCorpus(corpus);
     auto ex = createExecutors(domCorpus);
     if(! ex)
         return ex.error();
@@ -83,7 +84,7 @@ buildOne(
     std::ostream& os,
     Corpus const& corpus) const
 {
-    DomCorpus domCorpus(corpus);
+    AdocCorpus domCorpus(corpus);
     auto ex = createExecutors(domCorpus);
     if(! ex)
         return ex.error();