[clang-doc] Do not serialize empty text comments #169087
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Member
|
@llvm/pr-subscribers-clang-tools-extra Author: Erick Velez (evelez7) ChangesFull diff: https://github.com/llvm/llvm-project/pull/169087.diff 3 Files Affected:
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": [
|
🐧 Linux x64 Test Results
|
ilovepi
reviewed
Nov 21, 2025
| static void insertComment(Object &Description, json::Value &Comment, | ||
| StringRef Key) { | ||
| auto *TextCommentArray = Comment.getAsArray(); | ||
| if (TextCommentArray && TextCommentArray->empty()) |
Contributor
There was a problem hiding this comment.
Suggested change
| if (TextCommentArray && TextCommentArray->empty()) | |
| if (!TextCommentArray || TextCommentArray->empty()) |
Is this more along the lines of what you're after? Return early if we don't get something valid back?
Member
Author
There was a problem hiding this comment.
I actually had to rework this bit because I forgot that certain comments aren't just arrays of text. Param comments actually have attributes alongside the array.
evelez7
force-pushed
the
users/evelez7/clang-doc-empty-text-comments
branch
from
e1cd191 to
338350b
Compare
ilovepi
approved these changes
Nov 26, 2025
| 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(); Obj) { |
Contributor
There was a problem hiding this comment.
Suggested change
| if (auto *Obj = Comment.getAsObject(); Obj) { | |
| if (auto *Obj = Comment.getAsObject()) { |
Isn't this equivalent? Am I missing something?
Comment on lines
+130
to
+131
| if (!ChildObj) | ||
| break; |
Contributor
There was a problem hiding this comment.
you just return on the first one that isn't an object?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.