https://github.com/syedzohaibshah updated https://github.com/llvm/llvm-project/pull/188739
>From 84f3024d4b44d5bb810afdeaef74450003eaeda0 Mon Sep 17 00:00:00 2001 From: Zohaib Shah <[email protected]> Date: Thu, 26 Mar 2026 18:08:47 +0500 Subject: [PATCH] [clang-doc] Flatten repeated @return and @brief comment arrays Fixes #169006 --- clang-tools-extra/clang-doc/JSONGenerator.cpp | 34 ++++++++++++++----- .../json/multiple-return-comments.cpp | 30 ++++++++++++++++ 2 files changed, 56 insertions(+), 8 deletions(-) create mode 100644 clang-tools-extra/test/clang-doc/json/multiple-return-comments.cpp diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp index a9223cb9c3e8a..ef0d4d614a070 100644 --- a/clang-tools-extra/clang-doc/JSONGenerator.cpp +++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp @@ -133,8 +133,11 @@ json::Object JSONGenerator::serializeLocation(const Location &Loc) { /// /// \param Comment Either an Object or Array, depending on the comment type /// \param Key The type (Brief, Code, etc.) of comment to be inserted +/// \param FlattenArray If true and Comment is an array, merge its elements +/// instead of nesting. Used for BriefComments and +/// ReturnComments to avoid double-nested arrays. static void insertComment(Object &Description, json::Value &Comment, - StringRef Key) { + StringRef Key, bool FlattenArray = false) { // The comment has a Children array for the actual text, with meta attributes // alongside it in the Object. if (auto *Obj = Comment.getAsObject()) { @@ -150,11 +153,26 @@ static void insertComment(Object &Description, json::Value &Comment, auto DescriptionIt = Description.find(Key); if (DescriptionIt == Description.end()) { - auto CommentsArray = json::Array(); - CommentsArray.push_back(Comment); - Description[Key] = std::move(CommentsArray); + // For FlattenArray mode, if Comment is an array, use it directly + if (FlattenArray && Comment.getAsArray()) { + Description[Key] = Comment; + } else { + auto CommentsArray = json::Array(); + CommentsArray.push_back(Comment); + Description[Key] = std::move(CommentsArray); + } Description["Has" + Key.str()] = true; } else { + // For FlattenArray mode, if Comment is an array, merge its elements + if (FlattenArray) { + if (auto *CommentArray = Comment.getAsArray()) { + auto *DestArray = DescriptionIt->getSecond().getAsArray(); + for (auto &Element : *CommentArray) { + DestArray->push_back(Element); + } + return; + } + } DescriptionIt->getSecond().getAsArray()->push_back(Comment); } } @@ -217,10 +235,10 @@ static Object serializeComment(const CommentInfo &I, Object &Description) { case CommentKind::CK_BlockCommandComment: { auto TextCommentsArray = extractTextComments(CARef.front().getAsObject()); - if (I.Name == "brief") - insertComment(Description, TextCommentsArray, "BriefComments"); - else if (I.Name == "return") - insertComment(Description, TextCommentsArray, "ReturnComments"); + if (I.Name == "brief" || I.Name == "short") + insertComment(Description, TextCommentsArray, "BriefComments", true); + else if (I.Name == "return" || I.Name == "returns" || I.Name == "result") + insertComment(Description, TextCommentsArray, "ReturnComments", true); else if (I.Name == "throws" || I.Name == "throw") { json::Value ThrowsVal = Object(); auto &ThrowsObj = *ThrowsVal.getAsObject(); diff --git a/clang-tools-extra/test/clang-doc/json/multiple-return-comments.cpp b/clang-tools-extra/test/clang-doc/json/multiple-return-comments.cpp new file mode 100644 index 0000000000000..e1203a4115e78 --- /dev/null +++ b/clang-tools-extra/test/clang-doc/json/multiple-return-comments.cpp @@ -0,0 +1,30 @@ +// RUN: rm -rf %t && mkdir -p %t +// RUN: clang-doc --output=%t --format=json --executor=standalone %s +// RUN: FileCheck %s < %t/json/GlobalNamespace/index.json + +/// @brief Test function for multiple return comments +/// +/// @return First return value description +/// @return Second return value description +int testMultipleReturns() { + return 42; +} + +// CHECK: "Functions": [ +// CHECK-NEXT: { +// CHECK: "Description": { +// CHECK: "BriefComments": [ +// CHECK-NEXT: { +// CHECK-NEXT: "TextComment": "Test function for multiple return comments" +// CHECK-NEXT: } +// CHECK-NEXT: ], +// CHECK: "HasReturnComments": true, +// CHECK: "ReturnComments": [ +// CHECK-NEXT: { +// CHECK-NEXT: "TextComment": "First return value description" +// CHECK-NEXT: }, +// CHECK-NEXT: { +// CHECK-NEXT: "TextComment": "Second return value description" +// CHECK-NEXT: } +// CHECK-NEXT: ] +// CHECK: } _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
