[clang-doc] remove nesting of text comments inside paragraphs

Text comments were unnecessarily nested inside Paragraph comments as a
Children array. If they're at the top level, we can also avoid more
nesting in templates.

Author: evelez7

clang-tools-extra/clang-doc/JSONGenerator.cpp

@@ -97,6 +97,12 @@ static void insertComment(Object &Description, json::Value &Comment,
   }
 }
 
+static json::Value extractTextComments(Object *ParagraphComment) {
+  if (!ParagraphComment)
+    return json::Object();
+  return *ParagraphComment->get("Children");
+}
+
 static Object serializeComment(const CommentInfo &I, Object &Description) {
   // taken from PR #142273
   Object Obj = Object();
@@ -117,14 +123,9 @@ static Object serializeComment(const CommentInfo &I, Object &Description) {
   }
 
   case CommentKind::CK_BlockCommandComment: {
-    Child.insert({"Command", I.Name});
-    // TODO: The "Children" level of nesting isn't needed for comments that
-    // don't hold additional information at the top level. BriefComments can
-    // just be an array of ParagraphComments.
-    Child.insert({"Children", ChildArr});
-    Obj.insert({commentKindToString(I.Kind), ChildVal});
+    auto TextCommentsArray = extractTextComments(CARef.front().getAsObject());
     if (I.Name == "brief")
-      insertComment(Description, ChildVal, "BriefComments");
+      insertComment(Description, TextCommentsArray, "BriefComments");
     return Obj;
   }
 
@@ -201,8 +202,8 @@ static Object serializeComment(const CommentInfo &I, Object &Description) {
   case CommentKind::CK_FullComment:
   case CommentKind::CK_ParagraphComment: {
     Child.insert({"Children", ChildArr});
-    Obj.insert({commentKindToString(I.Kind), ChildVal});
-    return Obj;
+    Child["ParagraphComment"] = true;
+    return Child;
   }
 
   case CommentKind::CK_Unknown: {
@@ -239,9 +240,11 @@ serializeCommonAttributes(const Info &I, json::Object &Obj,
       json::Value Comment = serializeComment(*CommentInfo, Description);
       // if a ParagraphComment is returned, then it is a top-level comment that
       // needs to be inserted manually.
-      if (auto *ParagraphComment =
-              Comment.getAsObject()->get("ParagraphComment"))
-        insertComment(Description, *ParagraphComment, "ParagraphComments");
+      if (auto *ParagraphComment = Comment.getAsObject();
+          ParagraphComment->get("ParagraphComment")) {
+        auto TextCommentsArray = extractTextComments(ParagraphComment);
+        insertComment(Description, TextCommentsArray, "ParagraphComments");
+      }
     }
     Obj["Description"] = std::move(Description);
   }

clang-tools-extra/clang-doc/assets/comment-template.mustache

@@ -6,14 +6,18 @@
     This file defines templates for generating comments
 }}
 {{#BriefComments}}
-    {{#Children}}
-    {{>Comments}}
-    {{/Children}}
+    <div>
+    {{#.}}
+        <p>{{TextComment}}</p>
+    {{/.}}
+    </div>
 {{/BriefComments}}
 {{#ParagraphComments}}
-    {{#Children}}
-    {{>Comments}}
-    {{/Children}}
+    <div>
+    {{#.}}
+        <p>{{TextComment}}</p>
+    {{/.}}
+    </div>
 {{/ParagraphComments}}
 {{#ParagraphComment}}
     {{#Children}}

clang-tools-extra/test/clang-doc/json/class.cpp

@@ -35,28 +35,22 @@ struct MyClass {
 // CHECK:       {
 // CHECK-NEXT:    "Description": {
 // CHECK-NEXT:      "BriefComments": [
-// CHECK-NEXT:        {
-// CHECK-NEXT:          "Children": [
-// CHECK-NEXT:            {
-// CHECK-NEXT:              "ParagraphComment": {
-// CHECK-NEXT:                "Children": [
-// CHECK-NEXT:                  {
-// CHECK-NEXT:                    "TextComment": " This is a brief description."
-// CHECK:               "Command": "brief"
+// CHECK-NEXT:        [
+// CHECK-NEXT:          {
+// CHECK-NEXT:            "TextComment": " This is a brief description."
 // CHECK:           "HasBriefComments": true,
 // CHECK-NEXT:      "HasParagraphComments": true,
 // CHECK-NEXT:      "ParagraphComments": [
-// CHECK-NEXT:        {
-// CHECK-NEXT:          "Children": [
-// CHECK-NEXT:            {
-// CHECK-NEXT:              "TextComment": " This is a nice class."
-// CHECK-NEXT:            },
-// CHECK-NEXT:            {
-// CHECK-NEXT:              "TextComment": " It has some nice methods and fields."
-// CHECK-NEXT:            },
-// CHECK-NEXT:            {
-// CHECK-NEXT:              "TextComment": ""
-// CHECK-NEXT:            }
+// CHECK-NEXT:        [
+// CHECK-NEXT:          {
+// CHECK-NEXT:            "TextComment": " This is a nice class."
+// CHECK-NEXT:          },
+// CHECK-NEXT:          {
+// CHECK-NEXT:            "TextComment": " It has some nice methods and fields."
+// CHECK-NEXT:          },
+// CHECK-NEXT:          {
+// CHECK-NEXT:            "TextComment": ""
+// CHECK-NEXT:          }
 // CHECK:         "DocumentationFileName": "_ZTV7MyClass",
 // CHECK:         "Enums": [
 // CHECK-NEXT:      {

clang-tools-extra/test/clang-doc/json/concept.cpp

@@ -16,10 +16,9 @@ concept Incrementable = requires(T x) {
 // CHECK-NEXT:        "Description": {
 // CHECK-NEXT:        "HasParagraphComments": true,
 // CHECK-NEXT:        "ParagraphComments": [
-// CHECK-NEXT:          {
-// CHECK-NEXT:            "Children": [
-// CHECK-NEXT:              {
-// CHECK-NEXT:                "TextComment": " Requires that T suports post and pre-incrementing."
+// CHECK-NEXT:          [
+// CHECK-NEXT:            {
+// CHECK-NEXT:              "TextComment": " Requires that T suports post and pre-incrementing."
 // CHECK:             "End": true,
 // CHECK-NEXT:        "InfoType": "concept",
 // CHECK-NEXT:        "IsType": true,