[llvm-branch-commits] [clang-tools-extra] [clang-doc] remove nesting of text comments inside paragraphs (PR #150451)
Erick Velez via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Thu Jul 24 09:18:30 PDT 2025
https://github.com/evelez7 created https://github.com/llvm/llvm-project/pull/150451
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.
>From ff9bd90839f07d61a7deb35698d64edada538860 Mon Sep 17 00:00:00 2001
From: Erick Velez <erickvelez7 at gmail.com>
Date: Tue, 22 Jul 2025 20:12:35 -0700
Subject: [PATCH] [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.
---
clang-tools-extra/clang-doc/JSONGenerator.cpp | 27 +++++++++-------
.../assets/comment-template.mustache | 16 ++++++----
.../test/clang-doc/json/class.cpp | 32 ++++++++-----------
.../test/clang-doc/json/concept.cpp | 7 ++--
4 files changed, 41 insertions(+), 41 deletions(-)
diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index 75302b0dc3264..92a4117c4e534 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/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);
}
diff --git a/clang-tools-extra/clang-doc/assets/comment-template.mustache b/clang-tools-extra/clang-doc/assets/comment-template.mustache
index b793bad55cf6c..f2edb1b2eb9ac 100644
--- a/clang-tools-extra/clang-doc/assets/comment-template.mustache
+++ b/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}}
diff --git a/clang-tools-extra/test/clang-doc/json/class.cpp b/clang-tools-extra/test/clang-doc/json/class.cpp
index e8fafca28a956..79b8fed0a0188 100644
--- a/clang-tools-extra/test/clang-doc/json/class.cpp
+++ b/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: {
diff --git a/clang-tools-extra/test/clang-doc/json/concept.cpp b/clang-tools-extra/test/clang-doc/json/concept.cpp
index 2874caf28f8f5..4c810244ca41b 100644
--- a/clang-tools-extra/test/clang-doc/json/concept.cpp
+++ b/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,
More information about the llvm-branch-commits
mailing list