chore: Javadoc::makeOverview

Author: vinniefalco

include/mrdox/Metadata/Javadoc.hpp

@@ -557,6 +557,15 @@ void traverse(
             std::forward<Args>(args)...);
 }
 
+struct Overview
+{
+    Paragraph const* brief;
+    std::vector<Block const*> blocks;
+    Returns const* returns;
+    std::vector<Param const*> params;
+    std::vector<TParam const*> tparams;
+};
+
 } // doc
 
 //------------------------------------------------
@@ -566,9 +575,6 @@ void traverse(
 struct MRDOX_VISIBLE
     Javadoc
 {
-
-    //--------------------------------------------
-
     MRDOX_DECL
     Javadoc() noexcept;
 
@@ -673,6 +679,21 @@ struct MRDOX_VISIBLE
     void
     postProcess();
 
+    /** 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.
+    */
+    MRDOX_DECL doc::Overview makeOverview() const;
+
     //--------------------------------------------
 
     /** These are used to bottleneck all insertions.

source/Metadata/Javadoc.cpp

@@ -18,6 +18,55 @@
 namespace clang {
 namespace mrdox {
 
+namespace doc {
+
+static
+Overview
+makeOverview(
+    List<Block> const& list)
+{
+    doc::Overview ov;
+
+    // VFALCO dupes should already be reported as
+    // warnings or errors by now so we don't have
+    // to care about it here.
+
+    for(auto it = list.begin();
+        it != list.end(); ++it)
+    {
+        switch((*it)->kind)
+        {
+        case Kind::brief:
+            ov.brief = static_cast<
+                Paragraph const*>(it->get());
+            break;
+        case Kind::returns:
+            ov.returns = static_cast<
+                Returns const*>(it->get());
+            break;
+        case Kind::param:
+            ov.params.push_back(static_cast<
+                Param const*>(it->get()));
+            break;
+        case Kind::tparam:
+            ov.tparams.push_back(static_cast<
+                TParam const*>(it->get()));
+            break;
+        case Kind::paragraph:
+            ov.brief = static_cast<
+                Paragraph const*>(it->get());
+            break;
+        default:
+            ov.blocks.push_back(it->get());
+            break;
+        }
+    }
+
+    return ov;
+}
+
+} // doc
+
 //------------------------------------------------
 
 template<typename T, typename U>
@@ -170,5 +219,14 @@ postProcess()
     // as the brief when no written brief exists?
 }
 
+//------------------------------------------------
+
+doc::Overview
+Javadoc::
+makeOverview() const
+{
+    return doc::makeOverview(blocks_);
+}
+
 } // mrdox
 } // clang