[clang-tools-extra] [clang-doc] Do not serialize empty text comments (PR #169087)
Erick Velez via cfe-commits
cfe-commits at lists.llvm.org
Fri Nov 21 11:35:08 PST 2025
https://github.com/evelez7 created https://github.com/llvm/llvm-project/pull/169087
None
>From e1cd1911b74f08f8326868262bedff33ab9ac2f3 Mon Sep 17 00:00:00 2001
From: Erick Velez <erickvelez7 at gmail.com>
Date: Wed, 19 Nov 2025 22:01:13 -0800
Subject: [PATCH] [clang-doc] Do not serialize empty text comments
---
clang-tools-extra/clang-doc/JSONGenerator.cpp | 34 ++++++-
.../clang-doc/basic-project.mustache.test | 97 -------------------
.../test/clang-doc/json/class.cpp | 3 -
3 files changed, 32 insertions(+), 102 deletions(-)
diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index 97c599a3f605c..c65dcd34e37f4 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp
@@ -84,8 +84,13 @@ serializeLocation(const Location &Loc,
return LocationObj;
}
+/// \param Comment A json::Array possibly containing TextComments
+/// \param Key The type (Brief, Code) of comment to be inserted
static void insertComment(Object &Description, json::Value &Comment,
StringRef Key) {
+ auto *TextCommentArray = Comment.getAsArray();
+ if (TextCommentArray && TextCommentArray->empty())
+ return;
auto DescriptionIt = Description.find(Key);
if (DescriptionIt == Description.end()) {
@@ -100,8 +105,29 @@ static void insertComment(Object &Description, json::Value &Comment,
static json::Value extractTextComments(Object *ParagraphComment) {
if (!ParagraphComment)
- return json::Object();
- return *ParagraphComment->get("Children");
+ return nullptr;
+ json::Value *Children = ParagraphComment->get("Children");
+ if (!Children)
+ return nullptr;
+ auto ChildrenArray = *Children->getAsArray();
+ auto ChildrenIt = ChildrenArray.begin();
+ while (ChildrenIt != ChildrenArray.end()) {
+ auto *ChildObj = ChildrenIt->getAsObject();
+ if (!ChildObj)
+ break;
+ auto TextComment = ChildObj->getString("TextComment");
+ if (!TextComment) {
+ ChildrenIt = ChildrenArray.erase(ChildrenIt);
+ continue;
+ }
+
+ if (TextComment->empty()) {
+ ChildrenIt = ChildrenArray.erase(ChildrenIt);
+ continue;
+ }
+ ++ChildrenIt;
+ }
+ return ChildrenArray;
}
static json::Value extractVerbatimComments(json::Array VerbatimLines) {
@@ -131,6 +157,8 @@ static Object serializeComment(const CommentInfo &I, Object &Description) {
switch (I.Kind) {
case CommentKind::CK_TextComment: {
+ if (I.Text.empty())
+ return Obj;
Obj.insert({commentKindToString(I.Kind), I.Text});
return Obj;
}
@@ -265,6 +293,8 @@ serializeCommonAttributes(const Info &I, json::Object &Obj,
if (auto *ParagraphComment = Comment.getAsObject();
ParagraphComment->get("ParagraphComment")) {
auto TextCommentsArray = extractTextComments(ParagraphComment);
+ if (TextCommentsArray.kind() == json::Value::Null)
+ continue;
insertComment(Description, TextCommentsArray, "ParagraphComments");
}
}
diff --git a/clang-tools-extra/test/clang-doc/basic-project.mustache.test b/clang-tools-extra/test/clang-doc/basic-project.mustache.test
index 9f7de6e689313..2e64d42d42b81 100644
--- a/clang-tools-extra/test/clang-doc/basic-project.mustache.test
+++ b/clang-tools-extra/test/clang-doc/basic-project.mustache.test
@@ -65,9 +65,6 @@ HTML-SHAPE: <div>
HTML-SHAPE: <p> Abstract base class for shapes.</p>
HTML-SHAPE: </div>
HTML-SHAPE: <div>
-HTML-SHAPE: <p></p>
-HTML-SHAPE: </div>
-HTML-SHAPE: <div>
HTML-SHAPE: <p> Provides a common interface for different types of shapes.</p>
HTML-SHAPE: </div>
HTML-SHAPE: </div>
@@ -83,12 +80,6 @@ HTML-SHAPE: <div>
HTML-SHAPE: <div>
HTML-SHAPE: <p> Calculates the area of the shape.</p>
HTML-SHAPE: </div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p></p>
-HTML-SHAPE: </div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p></p>
-HTML-SHAPE: </div>
HTML-SHAPE: <h3>Returns</h3>
HTML-SHAPE: <p> double The area of the shape.</p>
HTML-SHAPE: </div>
@@ -101,12 +92,6 @@ HTML-SHAPE: <div>
HTML-SHAPE: <div>
HTML-SHAPE: <p> Calculates the perimeter of the shape.</p>
HTML-SHAPE: </div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p></p>
-HTML-SHAPE: </div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p></p>
-HTML-SHAPE: </div>
HTML-SHAPE: <h3>Returns</h3>
HTML-SHAPE: <p> double The perimeter of the shape.</p>
HTML-SHAPE: </div>
@@ -119,9 +104,6 @@ HTML-SHAPE: <div>
HTML-SHAPE: <div>
HTML-SHAPE: <p> Virtual destructor.</p>
HTML-SHAPE: </div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p></p>
-HTML-SHAPE: </div>
HTML-SHAPE: </div>
HTML-SHAPE: </div>
HTML-SHAPE: </div>
@@ -210,9 +192,6 @@ HTML-CALC: <div>
HTML-CALC: <p> A simple calculator class.</p>
HTML-CALC: </div>
HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <div>
HTML-CALC: <p> Provides basic arithmetic operations.</p>
HTML-CALC: </div>
HTML-CALC: </div>
@@ -239,12 +218,6 @@ HTML-CALC: <div>
HTML-CALC: <div>
HTML-CALC: <p> Adds two integers.</p>
HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
HTML-CALC: <h3>Parameters</h3>
HTML-CALC: <div>
HTML-CALC: <b>a</b> First integer.
@@ -264,12 +237,6 @@ HTML-CALC: <div>
HTML-CALC: <div>
HTML-CALC: <p> Subtracts the second integer from the first.</p>
HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
HTML-CALC: <h3>Parameters</h3>
HTML-CALC: <div>
HTML-CALC: <b>a</b> First integer.
@@ -289,12 +256,6 @@ HTML-CALC: <div>
HTML-CALC: <div>
HTML-CALC: <p> Multiplies two integers.</p>
HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
HTML-CALC: <h3>Parameters</h3>
HTML-CALC: <div>
HTML-CALC: <b>a</b> First integer.
@@ -314,12 +275,6 @@ HTML-CALC: <div>
HTML-CALC: <div>
HTML-CALC: <p> Divides the first integer by the second.</p>
HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
HTML-CALC: <h3>Parameters</h3>
HTML-CALC: <div>
HTML-CALC: <b>a</b> First integer.
@@ -329,7 +284,6 @@ HTML-CALC: <b>b</b> Second integer.
HTML-CALC: </div>
HTML-CALC: <h3>Returns</h3>
HTML-CALC: <p> double The result of a / b.</p>
-HTML-CALC: <p></p>
HTML-CALC: <h3>Throws</h3>
HTML-CALC: <div>
HTML-CALC: <b>std::invalid_argument</b> if b is zero.
@@ -344,12 +298,6 @@ HTML-CALC: <div>
HTML-CALC: <div>
HTML-CALC: <p> Performs the mod operation on integers.</p>
HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
HTML-CALC: <h3>Parameters</h3>
HTML-CALC: <div>
HTML-CALC: <b>a</b> First integer.
@@ -431,9 +379,6 @@ HTML-RECTANGLE: <div>
HTML-RECTANGLE: <p> Rectangle class derived from Shape.</p>
HTML-RECTANGLE: </div>
HTML-RECTANGLE: <div>
-HTML-RECTANGLE: <p></p>
-HTML-RECTANGLE: </div>
-HTML-RECTANGLE: <div>
HTML-RECTANGLE: <p> Represents a rectangle with a given width and height.</p>
HTML-RECTANGLE: </div>
HTML-RECTANGLE: </div>
@@ -449,12 +394,6 @@ HTML-RECTANGLE: <div>
HTML-RECTANGLE: <div>
HTML-RECTANGLE: <p> Constructs a new Rectangle object.</p>
HTML-RECTANGLE: </div>
-HTML-RECTANGLE: <div>
-HTML-RECTANGLE: <p></p>
-HTML-RECTANGLE: </div>
-HTML-RECTANGLE: <div>
-HTML-RECTANGLE: <p></p>
-HTML-RECTANGLE: </div>
HTML-RECTANGLE: <h3>Parameters</h3>
HTML-RECTANGLE: <div>
HTML-RECTANGLE: <b>width</b> Width of the rectangle.
@@ -472,12 +411,6 @@ HTML-RECTANGLE: <div>
HTML-RECTANGLE: <div>
HTML-RECTANGLE: <p> Calculates the area of the rectangle.</p>
HTML-RECTANGLE: </div>
-HTML-RECTANGLE: <div>
-HTML-RECTANGLE: <p></p>
-HTML-RECTANGLE: </div>
-HTML-RECTANGLE: <div>
-HTML-RECTANGLE: <p></p>
-HTML-RECTANGLE: </div>
HTML-RECTANGLE: <h3>Returns</h3>
HTML-RECTANGLE: <p> double The area of the rectangle.</p>
HTML-RECTANGLE: </div>
@@ -490,12 +423,6 @@ HTML-RECTANGLE: <div>
HTML-RECTANGLE: <div>
HTML-RECTANGLE: <p> Calculates the perimeter of the rectangle.</p>
HTML-RECTANGLE: </div>
-HTML-RECTANGLE: <div>
-HTML-RECTANGLE: <p></p>
-HTML-RECTANGLE: </div>
-HTML-RECTANGLE: <div>
-HTML-RECTANGLE: <p></p>
-HTML-RECTANGLE: </div>
HTML-RECTANGLE: <h3>Returns</h3>
HTML-RECTANGLE: <p> double The perimeter of the rectangle.</p>
HTML-RECTANGLE: </div>
@@ -570,9 +497,6 @@ HTML-CIRCLE: <div>
HTML-CIRCLE: <p> Circle class derived from Shape.</p>
HTML-CIRCLE: </div>
HTML-CIRCLE: <div>
-HTML-CIRCLE: <p></p>
-HTML-CIRCLE: </div>
-HTML-CIRCLE: <div>
HTML-CIRCLE: <p> Represents a circle with a given radius.</p>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
@@ -588,12 +512,6 @@ HTML-CIRCLE: <div>
HTML-CIRCLE: <div>
HTML-CIRCLE: <p> Constructs a new Circle object.</p>
HTML-CIRCLE: </div>
-HTML-CIRCLE: <div>
-HTML-CIRCLE: <p></p>
-HTML-CIRCLE: </div>
-HTML-CIRCLE: <div>
-HTML-CIRCLE: <p></p>
-HTML-CIRCLE: </div>
HTML-CIRCLE: <h3>Parameters</h3>
HTML-CIRCLE: <div>
HTML-CIRCLE: <b>radius</b> Radius of the circle.
@@ -608,12 +526,6 @@ HTML-CIRCLE: <div>
HTML-CIRCLE: <div>
HTML-CIRCLE: <p> Calculates the area of the circle.</p>
HTML-CIRCLE: </div>
-HTML-CIRCLE: <div>
-HTML-CIRCLE: <p></p>
-HTML-CIRCLE: </div>
-HTML-CIRCLE: <div>
-HTML-CIRCLE: <p></p>
-HTML-CIRCLE: </div>
HTML-CIRCLE: <h3>Returns</h3>
HTML-CIRCLE: <p> double The area of the circle.</p>
HTML-CIRCLE: </div>
@@ -626,15 +538,6 @@ HTML-CIRCLE: <div>
HTML-CIRCLE: <div>
HTML-CIRCLE: <p> Calculates the perimeter of the circle.</p>
HTML-CIRCLE: </div>
-HTML-CIRCLE: <div>
-HTML-CIRCLE: <p></p>
-HTML-CIRCLE: </div>
-HTML-CIRCLE: <div>
-HTML-CIRCLE: <p></p>
-HTML-CIRCLE: </div>
-HTML-CIRCLE: <div>
-HTML-CIRCLE: <p></p>
-HTML-CIRCLE: </div>
HTML-CIRCLE: <h3>Returns</h3>
HTML-CIRCLE: <p> double The perimeter of the circle.</p>
HTML-CIRCLE: <h3>Code</h3>
diff --git a/clang-tools-extra/test/clang-doc/json/class.cpp b/clang-tools-extra/test/clang-doc/json/class.cpp
index 91160585bef1a..8bf9402adf054 100644
--- a/clang-tools-extra/test/clang-doc/json/class.cpp
+++ b/clang-tools-extra/test/clang-doc/json/class.cpp
@@ -47,9 +47,6 @@ struct MyClass {
// 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": [
More information about the cfe-commits
mailing list