Skip to content

[clang-doc] separate comments into categories #149590

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.

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

Merged
merged 1 commit into from
Jul 25, 2025

Conversation

evelez7
Copy link
Member

@evelez7 evelez7 commented Jul 18, 2025

Comment categories will allow better comment organization in HTML.
Before, comments would just be serialized in whatever order they were
written, so groups like params or notes wouldn't be in the same
sections.

@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-integrate-json-to-mustache branch from b36a2d4 to c9f121a Compare July 21, 2025 16:45
@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-revamp-comments branch from e3d56c0 to eb171f6 Compare July 21, 2025 16:45
@evelez7 evelez7 marked this pull request as ready for review July 21, 2025 16:45
@llvmbot
Copy link
Member

llvmbot commented Jul 21, 2025

@llvm/pr-subscribers-clang-tools-extra

Author: Erick Velez (evelez7)

Changes

Comment categories will allow better comment organization in HTML.
Before, comments would just be serialized in whatever order they were
written, so groups like params or notes wouldn't be in the same
sections.


Full diff: https://github.com/llvm/llvm-project/pull/149590.diff

3 Files Affected:

  • (modified) clang-tools-extra/clang-doc/JSONGenerator.cpp (+34-9)
  • (modified) clang-tools-extra/test/clang-doc/json/class.cpp (+24-27)
  • (modified) clang-tools-extra/test/clang-doc/json/concept.cpp (+6-9)
diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index 908e23d24d079..5e2d60a8427e1 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp
@@ -83,7 +83,21 @@ serializeLocation(const Location &Loc,
   return LocationObj;
 }
 
-static json::Value serializeComment(const CommentInfo &I) {
+static void insertComment(Object &Description, json::Value &Comment,
+                          std::string Key) {
+  auto *CommentArray = Description.getArray(Key);
+  if (!CommentArray) {
+    auto CommentsArray = json::Array();
+    CommentsArray.push_back(Comment);
+    Description[Key] = std::move(CommentsArray);
+    Description["Has" + Key] = true;
+  } else {
+    CommentArray->push_back(Comment);
+    Description[Key] = std::move(*CommentArray);
+  }
+}
+
+static Object serializeComment(const CommentInfo &I, Object &Description) {
   // taken from PR #142273
   Object Obj = Object();
 
@@ -94,7 +108,7 @@ static json::Value serializeComment(const CommentInfo &I) {
   auto &CARef = *ChildArr.getAsArray();
   CARef.reserve(I.Children.size());
   for (const auto &C : I.Children)
-    CARef.emplace_back(serializeComment(*C));
+    CARef.emplace_back(serializeComment(*C, Description));
 
   switch (I.Kind) {
   case CommentKind::CK_TextComment: {
@@ -106,6 +120,8 @@ static json::Value serializeComment(const CommentInfo &I) {
     Child.insert({"Command", I.Name});
     Child.insert({"Children", ChildArr});
     Obj.insert({commentKindToString(I.Kind), ChildVal});
+    if (I.Name == "brief")
+      insertComment(Description, ChildVal, "BriefComments");
     return Obj;
   }
 
@@ -137,7 +153,10 @@ static json::Value serializeComment(const CommentInfo &I) {
     if (!I.CloseName.empty())
       Child.insert({"CloseName", I.CloseName});
     Child.insert({"Children", ChildArr});
-    Obj.insert({commentKindToString(I.Kind), ChildVal});
+    if (I.CloseName == "endcode")
+      insertComment(Description, ChildVal, "CodeComments");
+    else if (I.CloseName == "endverbatim")
+      insertComment(Description, ChildVal, "VerbatimComments");
     return Obj;
   }
 
@@ -210,12 +229,18 @@ serializeCommonAttributes(const Info &I, json::Object &Obj,
   }
 
   if (!I.Description.empty()) {
-    json::Value DescArray = json::Array();
-    auto &DescArrayRef = *DescArray.getAsArray();
-    DescArrayRef.reserve(I.Description.size());
-    for (const auto &Comment : I.Description)
-      DescArrayRef.push_back(serializeComment(Comment));
-    Obj["Description"] = DescArray;
+    Object Description = Object();
+    // Skip straight to the FullComment's children
+    auto &Comments = I.Description.at(0).Children;
+    for (const auto &CommentInfo : Comments) {
+      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");
+    }
+    Obj["Description"] = std::move(Description);
   }
 
   // Namespaces aren't SymbolInfos, so they dont have a DefLoc
diff --git a/clang-tools-extra/test/clang-doc/json/class.cpp b/clang-tools-extra/test/clang-doc/json/class.cpp
index a36358982b019..e8fafca28a956 100644
--- a/clang-tools-extra/test/clang-doc/json/class.cpp
+++ b/clang-tools-extra/test/clang-doc/json/class.cpp
@@ -33,33 +33,30 @@ struct MyClass {
 };
 
 // CHECK:       {
-// CHECK-NEXT:    "Description": [
-// CHECK-NEXT:      {
-// CHECK-NEXT:       "FullComment": {
-// CHECK-NEXT:         "Children": [
-// CHECK-NEXT:           {
-// CHECK-NEXT:             "ParagraphComment": {
-// 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:               {
-// CHECK-NEXT:             "BlockCommandComment": {
-// CHECK-NEXT:               "Children": [
-// CHECK-NEXT:                 {
-// CHECK-NEXT:                   "ParagraphComment": {
-// CHECK-NEXT:                     "Children": [
-// CHECK-NEXT:                       { 
-// CHECK-NEXT:                         "TextComment": " This is a brief description." 
-// CHECK-NEXT:                       }
-// CHECK:                   "Command": "brief"
+// 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:           "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:         "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 766415bbbeecd..2874caf28f8f5 100644
--- a/clang-tools-extra/test/clang-doc/json/concept.cpp
+++ b/clang-tools-extra/test/clang-doc/json/concept.cpp
@@ -13,16 +13,13 @@ concept Incrementable = requires(T x) {
 // CHECK-NEXT:    "Concepts": [
 // CHECK-NEXT:      {
 // CHECK-NEXT:        "ConstraintExpression": "requires (T x) { ++x; x++; }",
-// CHECK-NEXT:        "Description": [
+// CHECK-NEXT:        "Description": {
+// CHECK-NEXT:        "HasParagraphComments": true,
+// CHECK-NEXT:        "ParagraphComments": [
 // CHECK-NEXT:          {
-// CHECK-NEXT:            "FullComment": {
-// CHECK-NEXT:              "Children": [
-// CHECK-NEXT:                {
-// CHECK-NEXT:                  "ParagraphComment": {
-// CHECK-NEXT:                    "Children": [
-// CHECK-NEXT:                      {
-// CHECK-NEXT:                        "TextComment": " Requires that T suports post and pre-incrementing."
-// CHECK:             ],
+// CHECK-NEXT:            "Children": [
+// CHECK-NEXT:              {
+// CHECK-NEXT:                "TextComment": " Requires that T suports post and pre-incrementing."
 // CHECK:             "End": true,
 // CHECK-NEXT:        "InfoType": "concept",
 // CHECK-NEXT:        "IsType": true,

@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-revamp-comments branch from eb171f6 to d9bbda1 Compare July 21, 2025 17:58
@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-integrate-json-to-mustache branch from c9f121a to 2476174 Compare July 21, 2025 17:58
@evelez7 evelez7 requested review from ilovepi and petrhosek July 21, 2025 19:11
@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-integrate-json-to-mustache branch from 2476174 to bc443f0 Compare July 22, 2025 17:01
@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-revamp-comments branch 2 times, most recently from b4b103d to d82ff8e Compare July 23, 2025 03:53
@evelez7 evelez7 requested a review from ilovepi July 23, 2025 03:53
@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-integrate-json-to-mustache branch from bc443f0 to 7ecaad5 Compare July 23, 2025 19:55
@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-revamp-comments branch from d82ff8e to a4bb772 Compare July 23, 2025 19:56
Base automatically changed from users/evelez7/clang-doc-integrate-json-to-mustache to main July 23, 2025 22:20
Comment categories will allow better comment organization in HTML.
Before, comments would just be serialized in whatever order they were
written, so groups like params or notes wouldn't be in the same
sections.
Copy link
Member Author

evelez7 commented Jul 25, 2025

Merge activity

  • Jul 25, 1:34 AM UTC: A user started a stack merge that includes this pull request via Graphite.
  • Jul 25, 1:36 AM UTC: @evelez7 merged this pull request with Graphite.

@evelez7 evelez7 merged commit f361dd7 into main Jul 25, 2025
9 checks passed
@evelez7 evelez7 deleted the users/evelez7/clang-doc-revamp-comments branch July 25, 2025 01:36
mahesh-attarde pushed a commit to mahesh-attarde/llvm-project that referenced this pull request Jul 28, 2025
Comment categories will allow better comment organization in HTML.
Before, comments would just be serialized in whatever order they were
written, so groups like params or notes wouldn't be in the same
sections.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants