support unordered lists

#feat

fix #799

Author: alandefreitas

include/mrdocs/Metadata/Javadoc.hpp

@@ -116,6 +116,7 @@ enum class Kind
     heading,
     link,
     list_item,
+    unordered_list,
     paragraph,
     param,
     returns,
@@ -178,6 +179,12 @@ enum class Parts
 //--------------------------------------------
 
 /** This is a variant-like list element.
+
+    There are two types of nodes: text and block.
+
+    - The javadoc is a list of blocks.
+    - A block contains a list of text elements.
+    - A text element contains a string.
 */
 struct MRDOCS_DECL
     Node
@@ -367,6 +374,8 @@ struct Copied : Reference
 /** A piece of block content
 
     The top level is a list of blocks.
+
+    There are two types of blocks: headings and paragraphs
 */
 struct MRDOCS_DECL
     Block : Node
@@ -447,7 +456,7 @@ struct Heading : Block
     bool equals(const Node& other) const noexcept override
     {
         return kind == other.kind &&
-            *this == static_cast<const Heading&>(other);
+            *this == dynamic_cast<const Heading&>(other);
     }
 };
 
@@ -494,7 +503,7 @@ struct Brief : Paragraph
     bool equals(const Node& other) const noexcept override
     {
         return kind == other.kind &&
-            *this == static_cast<const Brief&>(other);
+            *this == dynamic_cast<const Brief&>(other);
     }
 };
 
@@ -520,7 +529,7 @@ struct Admonition : Paragraph
     bool equals(const Node& other) const noexcept override
     {
         return kind == other.kind &&
-            *this == static_cast<const Admonition&>(other);
+            *this == dynamic_cast<const Admonition&>(other);
     }
 };
 
@@ -542,7 +551,7 @@ struct Code : Paragraph
     bool equals(const Node& other) const noexcept override
     {
         return kind == other.kind &&
-            *this == static_cast<const Code&>(other);
+            *this == dynamic_cast<const Code&>(other);
     }
 };
 
@@ -563,7 +572,31 @@ struct ListItem : Paragraph
     bool equals(const Node& other) const noexcept override
     {
         return kind == other.kind &&
-            *this == static_cast<const ListItem&>(other);
+            *this == dynamic_cast<const ListItem&>(other);
+    }
+};
+
+/** A list of list items
+*/
+struct UnorderedList : Paragraph
+{
+    static constexpr Kind static_kind = Kind::unordered_list;
+
+    // Vector of list items
+    List<ListItem> items;
+
+    UnorderedList()
+        : Paragraph(Kind::unordered_list)
+    {
+    }
+
+    bool operator==(const UnorderedList&)
+        const noexcept = default;
+
+    bool equals(const Node& other) const noexcept override
+    {
+        return kind == other.kind &&
+            *this == dynamic_cast<const UnorderedList&>(other);
     }
 };
 
@@ -784,6 +817,8 @@ visit(
         return f.template operator()<Copied>(std::forward<Args>(args)...);
     case Kind::list_item:
         return f.template operator()<ListItem>(std::forward<Args>(args)...);
+    case Kind::unordered_list:
+        return f.template operator()<UnorderedList>(std::forward<Args>(args)...);
     case Kind::paragraph:
         return f.template operator()<Paragraph>(std::forward<Args>(args)...);
     case Kind::param:
@@ -851,6 +886,8 @@ visit(
         return visitor.template visit<Copied>();
     case Kind::list_item:
         return visitor.template visit<ListItem>();
+    case Kind::unordered_list:
+        return visitor.template visit<UnorderedList>();
     case Kind::param:
         return visitor.template visit<Param>();
     case Kind::returns:
@@ -917,12 +954,11 @@ class Corpus;
 
 /** A processed Doxygen-style comment attached to a declaration.
 */
-class MRDOCS_DECL
+struct MRDOCS_DECL
     Javadoc
 {
     doc::List<doc::Block> blocks_;
 
-public:
     /** Constructor.
     */
     MRDOCS_DECL

include/mrdocs/MetadataFwd.hpp

@@ -41,7 +41,7 @@ struct Type##Info;
 
 struct BaseInfo;
 struct Info;
-class Javadoc;
+struct Javadoc;
 struct Location;
 struct NameInfo;
 struct Param;

mrdocs.rnc

@@ -386,14 +386,15 @@ grammar
 
     BlockNode = (
         Admonition | Brief | Code | Heading | ListItem |
-        Paragraph | Param | Returns | TParam | Throws |
-        See | Precondition | Postcondition | Details)
+        UnorderedList | Paragraph | Param | Returns | TParam |
+        Throws | See | Precondition | Postcondition | Details)
 
     Admonition = Paragraph
     Brief = element brief { TextNode * }
     Code = element code { TextNode* }
     Heading = element head { text }
     ListItem = element listitem { TextNode* }
+    UnorderedList = element unorderedlist { ListItem * }
     Paragraph = element para {
         attribute class { text } ?,
         TextNode * }

src/lib/AST/ParseJavadoc.cpp

@@ -39,7 +39,7 @@
 #define MRDOCS_COMMENT_TRACE(D, C)
 #else
 
-#    define MRDOCS_COMMENT_TRACE_MERGE_(a, b) a##b
+#    define MRDOCS_COMMENT_TRACE_MERGE_(a, b) a## b
 #    define MRDOCS_COMMENT_TRACE_LABEL_(a)    MRDOCS_COMMENT_TRACE_MERGE_(comment_content_, a)
 #    define MRDOCS_COMMENT_TRACE_UNIQUE_NAME  MRDOCS_COMMENT_TRACE_LABEL_(__LINE__)
 
@@ -564,7 +564,7 @@ visitChildren(
     {
         MRDOCS_COMMENT_TRACE(*it_, ctx_);
         visit(*it_);
-        ++it_; // must happen after
+        ++it_;
     }
 
     if (!block_)
@@ -649,6 +649,35 @@ build()
 {
     MRDOCS_COMMENT_TRACE(FC_, ctx_);
     visit(FC_);
+
+    // Merge ListItems into UnorderedList
+    auto& blocks = jd_.getBlocks();
+    for (auto it = blocks.begin(); it != blocks.end(); ) {
+        if ((*it)->kind == doc::Kind::list_item) {
+            doc::UnorderedList ul;
+            // Find last list item
+            auto const begin = it;
+            auto last = it;
+            while (last != blocks.end() && (*last)->kind == doc::Kind::list_item) {
+                ++last;
+            }
+            // Move list items to ul.items
+            ul.items.reserve(std::distance(it, last));
+            for (auto li_it = begin; li_it != last; ++li_it) {
+                std::unique_ptr<doc::Block> block = std::move(*li_it);
+                MRDOCS_ASSERT(dynamic_cast<doc::ListItem*>(block.get()));
+                doc::Block* raw_block_ptr = block.release();
+                auto const raw_li_ptr = static_cast<doc::ListItem*>(raw_block_ptr);
+                auto li = std::make_unique<doc::ListItem>(std::move(*raw_li_ptr));
+                ul.items.emplace_back(std::move(li));
+            }
+            // Remove the list items and insert the ul
+            it = blocks.erase(begin, last);
+            it = blocks.insert(it, std::make_unique<doc::UnorderedList>(std::move(ul)));
+        }
+        ++it;
+    }
+
     return std::move(jd_);
 }
 

src/lib/Gen/adoc/DocVisitor.cpp

@@ -170,9 +170,11 @@ operator()(
     doc::ListItem const& I) const
 {
     std::span children = I.children;
-    if(children.empty())
+    if (children.empty())
+    {
         return;
-    dest_.append("\n* ");
+    }
+    dest_.append("* ");
     bool non_empty = write(*children.front(), *this);
     for(auto const& child : children.subspan(1))
     {
@@ -185,6 +187,22 @@ operator()(
     dest_.push_back('\n');
 }
 
+void
+DocVisitor::
+operator()(
+    doc::UnorderedList const& I) const
+{
+    if (I.items.empty())
+    {
+        return;
+    }
+    for(auto const& child : I.items)
+    {
+        operator()(*child);
+    }
+    dest_.push_back('\n');
+}
+
 void
 DocVisitor::
 operator()(doc::Param const& I) const

src/lib/Gen/adoc/DocVisitor.hpp

@@ -68,6 +68,9 @@ class DocVisitor
     void
     operator()(doc::ListItem const& I) const;
 
+    void
+    operator()(doc::UnorderedList const& I) const;
+
     void
     operator()(doc::Param const& I) const;
 

src/lib/Gen/html/DocVisitor.cpp

@@ -211,6 +211,23 @@ operator()(
     dest_.append("</li>\n");
 }
 
+void
+DocVisitor::
+operator()(
+    doc::UnorderedList const& I) const
+{
+    if (I.items.empty())
+    {
+        return;
+    }
+    dest_.append("<ul>\n");
+    for(auto const& child : I.items)
+    {
+        operator()(*child);
+    }
+    dest_.append("</ul>\n");
+}
+
 void
 DocVisitor::
 operator()(doc::Param const& I) const

src/lib/Gen/html/DocVisitor.hpp

@@ -68,6 +68,9 @@ class DocVisitor
     void
     operator()(doc::ListItem const& I) const;
 
+    void
+    operator()(doc::UnorderedList const& I) const;
+
     void
     operator()(doc::Param const& I) const;
 

src/lib/Gen/xml/XMLWriter.cpp

@@ -747,6 +747,9 @@ writeNode(
     case doc::Kind::list_item:
         writeListItem(dynamic_cast<doc::ListItem const&>(node));
         break;
+    case doc::Kind::unordered_list:
+        writeUnorderedList(dynamic_cast<doc::UnorderedList const&>(node));
+        break;
     case doc::Kind::brief:
         writeBrief(dynamic_cast<doc::Brief const&>(node));
         break;
@@ -847,6 +850,16 @@ writeListItem(
     tags_.close("listitem");
 }
 
+void
+XMLWriter::
+writeUnorderedList(
+    doc::UnorderedList const& node)
+{
+    tags_.open("unorderedlist");
+    writeNodes(node.items);
+    tags_.close("unorderedlist");
+}
+
 void
 XMLWriter::
 writeBrief(

src/lib/Gen/xml/XMLWriter.hpp

@@ -81,6 +81,7 @@ class XMLWriter
     void writeHeading(doc::Heading const& node);
     void writeLink(doc::Link const& node);
     void writeListItem(doc::ListItem const& node);
+    void writeUnorderedList(doc::UnorderedList const& node);
     void writeParagraph(doc::Paragraph const& node, llvm::StringRef tag = "");
     void writeJParam(doc::Param const& node);
     void writeReturns(doc::Returns const& node);