https://github.com/evelez7 updated https://github.com/llvm/llvm-project/pull/169087
>From 58a8e1e0ea45711e3e326a306e5065090eda6bb1 Mon Sep 17 00:00:00 2001 From: Erick Velez <[email protected]> Date: Wed, 19 Nov 2025 22:01:13 -0800 Subject: [PATCH] Address review feedback, handle extraction better --- clang-tools-extra/clang-doc/JSONGenerator.cpp | 47 ++++++++- .../clang-doc/basic-project.mustache.test | 97 ------------------- .../test/clang-doc/json/class.cpp | 3 - 3 files changed, 44 insertions(+), 103 deletions(-) diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp index 97c599a3f605c..41983d5f938fc 100644 --- a/clang-tools-extra/clang-doc/JSONGenerator.cpp +++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp @@ -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()) { + 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 || Array->empty()) { + return; + } + auto DescriptionIt = Description.find(Key); if (DescriptionIt == Description.end()) { @@ -98,10 +114,31 @@ 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) { + ++ChildrenIt; + continue; + } + 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 +168,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 +303,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 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": [ _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
