Skip to content

[clang-doc] Do not serialize empty text comments #169087

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+42 −103
Open

[clang-doc] Do not serialize empty text comments #169087

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 42 additions & 3 deletions clang-tools-extra/clang-doc/JSONGenerator.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,24 @@ 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(); Obj) {
Copy link
Contributor

@ilovepi ilovepi Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
if (auto *Obj = Comment.getAsObject(); Obj) {
if (auto *Obj = Comment.getAsObject()) {

Isn't this equivalent? Am I missing something?

if (auto *Children = Obj->getArray("Children");
!Children || Children->empty())
return;
}
// The comment is just an array of text comments.
else if (auto *Array = Comment.getAsArray(); !Array) {
return;
}

auto DescriptionIt = Description.find(Key);

if (DescriptionIt == Description.end()) {
Expand All @@ -98,10 +114,29 @@ 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();
if (!ChildObj)
break;
Comment on lines +130 to +131
Copy link
Contributor

@ilovepi ilovepi Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you just return on the first one that isn't an object?

auto TextComment = ChildObj->getString("TextComment");
if (!TextComment || TextComment->empty()) {
ChildrenIt = ChildrenArray.erase(ChildrenIt);
continue;
}
++ChildrenIt;
}
return ChildrenArray;
}

static json::Value extractVerbatimComments(json::Array VerbatimLines) {
Expand Down Expand Up @@ -131,7 +166,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;
}

Expand Down Expand Up @@ -265,6 +301,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");
}
}
Expand Down
97 changes: 0 additions & 97 deletions clang-tools-extra/test/clang-doc/basic-project.mustache.test
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand Down Expand Up @@ -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>
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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>
Expand All @@ -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.
Expand All @@ -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>
Expand All @@ -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>
Expand Down Expand Up @@ -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>
Expand All @@ -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.
Expand All @@ -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>
Expand All @@ -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>
Expand Down
3 changes: 0 additions & 3 deletions clang-tools-extra/test/clang-doc/json/class.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down