[llvm-branch-commits] [clang-tools-extra] d86bc19 - [clang-doc] Do not serialize empty text comments (#169087)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Tue Dec 9 15:51:16 PST 2025
Author: Erick Velez
Date: 2025-12-09T13:37:00-08:00
New Revision: d86bc19ad79896b956c828a8f9c2c0d94d131466
URL: https://github.com/llvm/llvm-project/commit/d86bc19ad79896b956c828a8f9c2c0d94d131466
DIFF: https://github.com/llvm/llvm-project/commit/d86bc19ad79896b956c828a8f9c2c0d94d131466.diff
LOG: [clang-doc] Do not serialize empty text comments (#169087)
Added:
Modified:
clang-tools-extra/clang-doc/JSONGenerator.cpp
clang-tools-extra/test/clang-doc/basic-project.mustache.test
clang-tools-extra/test/clang-doc/json/class.cpp
Removed:
################################################################################
diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index 97c599a3f605c..77aa8794561e4 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp
@@ -84,8 +84,23 @@ serializeLocation(const Location &Loc,
return LocationObj;
}
+/// Insert comments into a key in the Description object.
+///
+/// \param Comment Either an Object or Array, depending on the comment type
+/// \param Key The type (Brief, Code, etc.) of comment to be inserted
static void insertComment(Object &Description, json::Value &Comment,
StringRef Key) {
+ // The comment has a Children array for the actual text, with meta attributes
+ // alongside it in the Object.
+ if (auto *Obj = Comment.getAsObject()) {
+ if (auto *Children = Obj->getArray("Children"); Children->empty())
+ return;
+ }
+ // The comment is just an array of text comments.
+ else if (auto *Array = Comment.getAsArray(); Array->empty()) {
+ return;
+ }
+
auto DescriptionIt = Description.find(Key);
if (DescriptionIt == Description.end()) {
@@ -98,10 +113,28 @@ static void insertComment(Object &Description, json::Value &Comment,
}
}
+/// Takes the nested "Children" array from a comment Object.
+///
+/// \return a json::Array of comments, possible json::Value::Kind::Null
static json::Value extractTextComments(Object *ParagraphComment) {
if (!ParagraphComment)
- return json::Object();
- return *ParagraphComment->get("Children");
+ return json::Value(nullptr);
+ json::Value *Children = ParagraphComment->get("Children");
+ if (!Children)
+ return json::Value(nullptr);
+ auto ChildrenArray = *Children->getAsArray();
+ auto ChildrenIt = ChildrenArray.begin();
+ while (ChildrenIt != ChildrenArray.end()) {
+ auto *ChildObj = ChildrenIt->getAsObject();
+ assert(ChildObj && "Invalid JSON object in Comment");
+ auto TextComment = ChildObj->getString("TextComment");
+ if (!TextComment || TextComment->empty()) {
+ ChildrenIt = ChildrenArray.erase(ChildrenIt);
+ continue;
+ }
+ ++ChildrenIt;
+ }
+ return ChildrenArray;
}
static json::Value extractVerbatimComments(json::Array VerbatimLines) {
@@ -131,7 +164,8 @@ static Object serializeComment(const CommentInfo &I, Object &Description) {
switch (I.Kind) {
case CommentKind::CK_TextComment: {
- Obj.insert({commentKindToString(I.Kind), I.Text});
+ if (!I.Text.empty())
+ Obj.insert({commentKindToString(I.Kind), I.Text});
return Obj;
}
@@ -265,6 +299,9 @@ 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 ||
+ TextCommentsArray.getAsArray()->empty())
+ 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 282ca73384c3f..b985a39265de7 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
diff erent 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 llvm-branch-commits
mailing list