Author: Erick Velez Date: 2025-07-24T19:49:54-07:00 New Revision: 2ca8cf922ff8f9498ae0f9def9dab9bf145c6653
URL: https://github.com/llvm/llvm-project/commit/2ca8cf922ff8f9498ae0f9def9dab9bf145c6653 DIFF: https://github.com/llvm/llvm-project/commit/2ca8cf922ff8f9498ae0f9def9dab9bf145c6653.diff LOG: [clang-doc] remove nesting of text comments inside paragraphs (#150451) Text comments were unnecessarily nested inside Paragraph comments as a Children array. If they're at the top level, we can also avoid more nesting in templates. Added: Modified: clang-tools-extra/clang-doc/JSONGenerator.cpp clang-tools-extra/clang-doc/assets/comment-template.mustache clang-tools-extra/test/clang-doc/json/class.cpp clang-tools-extra/test/clang-doc/json/concept.cpp Removed: ################################################################################ diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp index 75302b0dc3264..92a4117c4e534 100644 --- a/clang-tools-extra/clang-doc/JSONGenerator.cpp +++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp @@ -97,6 +97,12 @@ static void insertComment(Object &Description, json::Value &Comment, } } +static json::Value extractTextComments(Object *ParagraphComment) { + if (!ParagraphComment) + return json::Object(); + return *ParagraphComment->get("Children"); +} + static Object serializeComment(const CommentInfo &I, Object &Description) { // taken from PR #142273 Object Obj = Object(); @@ -117,14 +123,9 @@ static Object serializeComment(const CommentInfo &I, Object &Description) { } case CommentKind::CK_BlockCommandComment: { - Child.insert({"Command", I.Name}); - // TODO: The "Children" level of nesting isn't needed for comments that - // don't hold additional information at the top level. BriefComments can - // just be an array of ParagraphComments. - Child.insert({"Children", ChildArr}); - Obj.insert({commentKindToString(I.Kind), ChildVal}); + auto TextCommentsArray = extractTextComments(CARef.front().getAsObject()); if (I.Name == "brief") - insertComment(Description, ChildVal, "BriefComments"); + insertComment(Description, TextCommentsArray, "BriefComments"); return Obj; } @@ -201,8 +202,8 @@ static Object serializeComment(const CommentInfo &I, Object &Description) { case CommentKind::CK_FullComment: case CommentKind::CK_ParagraphComment: { Child.insert({"Children", ChildArr}); - Obj.insert({commentKindToString(I.Kind), ChildVal}); - return Obj; + Child["ParagraphComment"] = true; + return Child; } case CommentKind::CK_Unknown: { @@ -239,9 +240,11 @@ serializeCommonAttributes(const Info &I, json::Object &Obj, json::Value Comment = serializeComment(*CommentInfo, Description); // if a ParagraphComment is returned, then it is a top-level comment that // needs to be inserted manually. - if (auto *ParagraphComment = - Comment.getAsObject()->get("ParagraphComment")) - insertComment(Description, *ParagraphComment, "ParagraphComments"); + if (auto *ParagraphComment = Comment.getAsObject(); + ParagraphComment->get("ParagraphComment")) { + auto TextCommentsArray = extractTextComments(ParagraphComment); + insertComment(Description, TextCommentsArray, "ParagraphComments"); + } } Obj["Description"] = std::move(Description); } diff --git a/clang-tools-extra/clang-doc/assets/comment-template.mustache b/clang-tools-extra/clang-doc/assets/comment-template.mustache index b793bad55cf6c..f2edb1b2eb9ac 100644 --- a/clang-tools-extra/clang-doc/assets/comment-template.mustache +++ b/clang-tools-extra/clang-doc/assets/comment-template.mustache @@ -6,14 +6,18 @@ This file defines templates for generating comments }} {{#BriefComments}} - {{#Children}} - {{>Comments}} - {{/Children}} + <div> + {{#.}} + <p>{{TextComment}}</p> + {{/.}} + </div> {{/BriefComments}} {{#ParagraphComments}} - {{#Children}} - {{>Comments}} - {{/Children}} + <div> + {{#.}} + <p>{{TextComment}}</p> + {{/.}} + </div> {{/ParagraphComments}} {{#ParagraphComment}} {{#Children}} diff --git a/clang-tools-extra/test/clang-doc/json/class.cpp b/clang-tools-extra/test/clang-doc/json/class.cpp index e8fafca28a956..79b8fed0a0188 100644 --- a/clang-tools-extra/test/clang-doc/json/class.cpp +++ b/clang-tools-extra/test/clang-doc/json/class.cpp @@ -35,28 +35,22 @@ struct MyClass { // CHECK: { // CHECK-NEXT: "Description": { // CHECK-NEXT: "BriefComments": [ -// CHECK-NEXT: { -// CHECK-NEXT: "Children": [ -// CHECK-NEXT: { -// CHECK-NEXT: "ParagraphComment": { -// CHECK-NEXT: "Children": [ -// CHECK-NEXT: { -// CHECK-NEXT: "TextComment": " This is a brief description." -// CHECK: "Command": "brief" +// CHECK-NEXT: [ +// CHECK-NEXT: { +// CHECK-NEXT: "TextComment": " This is a brief description." // CHECK: "HasBriefComments": true, // CHECK-NEXT: "HasParagraphComments": true, // CHECK-NEXT: "ParagraphComments": [ -// CHECK-NEXT: { -// CHECK-NEXT: "Children": [ -// CHECK-NEXT: { -// CHECK-NEXT: "TextComment": " This is a nice class." -// CHECK-NEXT: }, -// CHECK-NEXT: { -// CHECK-NEXT: "TextComment": " It has some nice methods and fields." -// CHECK-NEXT: }, -// CHECK-NEXT: { -// CHECK-NEXT: "TextComment": "" -// CHECK-NEXT: } +// CHECK-NEXT: [ +// CHECK-NEXT: { +// CHECK-NEXT: "TextComment": " This is a nice class." +// 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": [ // CHECK-NEXT: { diff --git a/clang-tools-extra/test/clang-doc/json/concept.cpp b/clang-tools-extra/test/clang-doc/json/concept.cpp index 2874caf28f8f5..4c810244ca41b 100644 --- a/clang-tools-extra/test/clang-doc/json/concept.cpp +++ b/clang-tools-extra/test/clang-doc/json/concept.cpp @@ -16,10 +16,9 @@ concept Incrementable = requires(T x) { // CHECK-NEXT: "Description": { // CHECK-NEXT: "HasParagraphComments": true, // CHECK-NEXT: "ParagraphComments": [ -// CHECK-NEXT: { -// CHECK-NEXT: "Children": [ -// CHECK-NEXT: { -// CHECK-NEXT: "TextComment": " Requires that T suports post and pre-incrementing." +// CHECK-NEXT: [ +// CHECK-NEXT: { +// CHECK-NEXT: "TextComment": " Requires that T suports post and pre-incrementing." // CHECK: "End": true, // CHECK-NEXT: "InfoType": "concept", // CHECK-NEXT: "IsType": true, _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
