[llvm-branch-commits] [clang-tools-extra] [clang-doc] add return comments to comment template (PR #150647)
Erick Velez via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Fri Jul 25 10:43:12 PDT 2025
https://github.com/evelez7 updated https://github.com/llvm/llvm-project/pull/150647
>From 6ca79fa19e505b36bc76a0bd2f062db1e0161b4a Mon Sep 17 00:00:00 2001
From: Erick Velez <erickvelez7 at gmail.com>
Date: Wed, 23 Jul 2025 11:25:05 -0700
Subject: [PATCH 1/2] [clang-doc] precommit return comments test
---
.../clang-doc/basic-project.mustache.test | 23 +++++++++++++++++++
1 file changed, 23 insertions(+)
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 b55e0abe2cdef..94391dc58bf25 100644
--- a/clang-tools-extra/test/clang-doc/basic-project.mustache.test
+++ b/clang-tools-extra/test/clang-doc/basic-project.mustache.test
@@ -93,6 +93,8 @@ HTML-SHAPE: </div>
HTML-SHAPE: <div>
HTML-SHAPE: <p></p>
HTML-SHAPE: </div>
+HTML-SHAPE-NOT: <h3>Returns</h3>
+HTML-SHAPE-NOT: <p> double The area of the shape.</p>
HTML-SHAPE: </div>
HTML-SHAPE: </div>
HTML-SHAPE: </div>
@@ -113,6 +115,8 @@ HTML-SHAPE: </div>
HTML-SHAPE: <div>
HTML-SHAPE: <p></p>
HTML-SHAPE: </div>
+HTML-SHAPE-NOT: <h3>Returns</h3>
+HTML-SHAPE-NOT: <p> double The perimeter of the shape.</p>
HTML-SHAPE: </div>
HTML-SHAPE: </div>
HTML-SHAPE: </div>
@@ -277,6 +281,8 @@ HTML-CALC: <div>
HTML-CALC: <p></p>
HTML-CALC: </div>
HTML-CALC: </div>
+HTML-CALC-NOT: <h3>Returns</h3>
+HTML-CALC-NOT: <p> int The sum of a and b.</p>
HTML-CALC: </div>
HTML-CALC: </div>
HTML-CALC: </div>
@@ -297,6 +303,8 @@ HTML-CALC: </div>
HTML-CALC: <div>
HTML-CALC: <p></p>
HTML-CALC: </div>
+HTML-CALC-NOT: <h3>Returns</h3>
+HTML-CALC-NOT: <p> int The result of a - b.</p>
HTML-CALC: </div>
HTML-CALC: </div>
HTML-CALC: </div>
@@ -334,6 +342,8 @@ HTML-CALC: <div>
HTML-CALC: <p></p>
HTML-CALC: </div>
HTML-CALC: </div>
+HTML-CALC-NOT: <h3>Returns</h3>
+HTML-CALC-NOT: <p> int The product of a and b.</p>
HTML-CALC: </div>
HTML-CALC: </div>
HTML-CALC: </div>
@@ -371,6 +381,9 @@ HTML-CALC: <div>
HTML-CALC: <p></p>
HTML-CALC: </div>
HTML-CALC: </div>
+HTML-CALC-NOT: <h3>Returns</h3>
+HTML-CALC-NOT: <p> double The result of a / b.</p>
+HTML-CALC-NOT: <p></p>
HTML-CALC: </div>
HTML-CALC: </div>
HTML-CALC: </div>
@@ -408,6 +421,8 @@ HTML-CALC: <div>
HTML-CALC: <p></p>
HTML-CALC: </div>
HTML-CALC: </div>
+HTML-CALC-NOT: <h3>Returns</h3>
+HTML-CALC-NOT: <p> The result of a % b.</p>
HTML-CALC: </div>
HTML-CALC: </div>
HTML-CALC: </div>
@@ -541,6 +556,8 @@ HTML-RECTANGLE: </div>
HTML-RECTANGLE: <div>
HTML-RECTANGLE: <p></p>
HTML-RECTANGLE: </div>
+HTML-RECTANGLE-NOT: <h3>Returns</h3>
+HTML-RECTANGLE-NOT: <p> double The area of the rectangle.</p>
HTML-RECTANGLE: </div>
HTML-RECTANGLE: </div>
HTML-RECTANGLE: </div>
@@ -561,6 +578,8 @@ HTML-RECTANGLE: </div>
HTML-RECTANGLE: <div>
HTML-RECTANGLE: <p></p>
HTML-RECTANGLE: </div>
+HTML-RECTANGLE-NOT: <h3>Returns</h3>
+HTML-RECTANGLE-NOT: <p> double The perimeter of the rectangle.</p>
HTML-RECTANGLE: </div>
HTML-RECTANGLE: </div>
HTML-RECTANGLE: </div>
@@ -686,6 +705,8 @@ HTML-CIRCLE: </div>
HTML-CIRCLE: <div>
HTML-CIRCLE: <p></p>
HTML-CIRCLE: </div>
+HTML-CIRCLE-NOT: <h3>Returns</h3>
+HTML-CIRCLE-NOT: <p> double The area of the circle.</p>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
@@ -706,6 +727,8 @@ HTML-CIRCLE: </div>
HTML-CIRCLE: <div>
HTML-CIRCLE: <p></p>
HTML-CIRCLE: </div>
+HTML-CIRCLE-NOT: <h3>Returns</h3>
+HTML-CIRCLE-NOT: <p> double The perimeter of the circle.</p>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
>From 6f19128ac9f7610b753844d6cb6e278e1dc21672 Mon Sep 17 00:00:00 2001
From: Erick Velez <erickvelez7 at gmail.com>
Date: Wed, 23 Jul 2025 11:12:25 -0700
Subject: [PATCH 2/2] [clang-doc] add return comments to comment template
Serialize return comments in HTML templates.
---
clang-tools-extra/clang-doc/JSONGenerator.cpp | 2 +
.../assets/comment-template.mustache | 8 ++++
.../clang-doc/basic-project.mustache.test | 46 +++++++++----------
3 files changed, 33 insertions(+), 23 deletions(-)
diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index 5fc28406ee870..cae1a686266c6 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp
@@ -126,6 +126,8 @@ static Object serializeComment(const CommentInfo &I, Object &Description) {
auto TextCommentsArray = extractTextComments(CARef.front().getAsObject());
if (I.Name == "brief")
insertComment(Description, TextCommentsArray, "BriefComments");
+ else if (I.Name == "return")
+ insertComment(Description, TextCommentsArray, "ReturnComments");
return Obj;
}
diff --git a/clang-tools-extra/clang-doc/assets/comment-template.mustache b/clang-tools-extra/clang-doc/assets/comment-template.mustache
index d55a53194ee5c..89c48d26278c0 100644
--- a/clang-tools-extra/clang-doc/assets/comment-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/comment-template.mustache
@@ -32,6 +32,14 @@
</div>
{{/ParamComments}}
{{/HasParamComments}}
+{{#HasReturnComments}}
+ <h3>Returns</h3>
+ {{#ReturnComments}}
+ {{#.}}
+ <p>{{TextComment}}</p>
+ {{/.}}
+ {{/ReturnComments}}
+{{/HasReturnComments}}
{{#BlockCommandComment}}
<div class="block-command-comment__command">
<div class="block-command-command">
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 94391dc58bf25..2c87fe2533195 100644
--- a/clang-tools-extra/test/clang-doc/basic-project.mustache.test
+++ b/clang-tools-extra/test/clang-doc/basic-project.mustache.test
@@ -93,8 +93,8 @@ HTML-SHAPE: </div>
HTML-SHAPE: <div>
HTML-SHAPE: <p></p>
HTML-SHAPE: </div>
-HTML-SHAPE-NOT: <h3>Returns</h3>
-HTML-SHAPE-NOT: <p> double The area of the shape.</p>
+HTML-SHAPE: <h3>Returns</h3>
+HTML-SHAPE: <p> double The area of the shape.</p>
HTML-SHAPE: </div>
HTML-SHAPE: </div>
HTML-SHAPE: </div>
@@ -115,8 +115,8 @@ HTML-SHAPE: </div>
HTML-SHAPE: <div>
HTML-SHAPE: <p></p>
HTML-SHAPE: </div>
-HTML-SHAPE-NOT: <h3>Returns</h3>
-HTML-SHAPE-NOT: <p> double The perimeter of the shape.</p>
+HTML-SHAPE: <h3>Returns</h3>
+HTML-SHAPE: <p> double The perimeter of the shape.</p>
HTML-SHAPE: </div>
HTML-SHAPE: </div>
HTML-SHAPE: </div>
@@ -281,8 +281,8 @@ HTML-CALC: <div>
HTML-CALC: <p></p>
HTML-CALC: </div>
HTML-CALC: </div>
-HTML-CALC-NOT: <h3>Returns</h3>
-HTML-CALC-NOT: <p> int The sum of a and b.</p>
+HTML-CALC: <h3>Returns</h3>
+HTML-CALC: <p> int The sum of a and b.</p>
HTML-CALC: </div>
HTML-CALC: </div>
HTML-CALC: </div>
@@ -303,8 +303,8 @@ HTML-CALC: </div>
HTML-CALC: <div>
HTML-CALC: <p></p>
HTML-CALC: </div>
-HTML-CALC-NOT: <h3>Returns</h3>
-HTML-CALC-NOT: <p> int The result of a - b.</p>
+HTML-CALC: <h3>Returns</h3>
+HTML-CALC: <p> int The result of a - b.</p>
HTML-CALC: </div>
HTML-CALC: </div>
HTML-CALC: </div>
@@ -342,8 +342,8 @@ HTML-CALC: <div>
HTML-CALC: <p></p>
HTML-CALC: </div>
HTML-CALC: </div>
-HTML-CALC-NOT: <h3>Returns</h3>
-HTML-CALC-NOT: <p> int The product of a and b.</p>
+HTML-CALC: <h3>Returns</h3>
+HTML-CALC: <p> int The product of a and b.</p>
HTML-CALC: </div>
HTML-CALC: </div>
HTML-CALC: </div>
@@ -381,9 +381,9 @@ HTML-CALC: <div>
HTML-CALC: <p></p>
HTML-CALC: </div>
HTML-CALC: </div>
-HTML-CALC-NOT: <h3>Returns</h3>
-HTML-CALC-NOT: <p> double The result of a / b.</p>
-HTML-CALC-NOT: <p></p>
+HTML-CALC: <h3>Returns</h3>
+HTML-CALC: <p> double The result of a / b.</p>
+HTML-CALC: <p></p>
HTML-CALC: </div>
HTML-CALC: </div>
HTML-CALC: </div>
@@ -421,8 +421,8 @@ HTML-CALC: <div>
HTML-CALC: <p></p>
HTML-CALC: </div>
HTML-CALC: </div>
-HTML-CALC-NOT: <h3>Returns</h3>
-HTML-CALC-NOT: <p> The result of a % b.</p>
+HTML-CALC: <h3>Returns</h3>
+HTML-CALC: <p> The result of a % b.</p>
HTML-CALC: </div>
HTML-CALC: </div>
HTML-CALC: </div>
@@ -556,8 +556,8 @@ HTML-RECTANGLE: </div>
HTML-RECTANGLE: <div>
HTML-RECTANGLE: <p></p>
HTML-RECTANGLE: </div>
-HTML-RECTANGLE-NOT: <h3>Returns</h3>
-HTML-RECTANGLE-NOT: <p> double The area of the rectangle.</p>
+HTML-RECTANGLE: <h3>Returns</h3>
+HTML-RECTANGLE: <p> double The area of the rectangle.</p>
HTML-RECTANGLE: </div>
HTML-RECTANGLE: </div>
HTML-RECTANGLE: </div>
@@ -578,8 +578,8 @@ HTML-RECTANGLE: </div>
HTML-RECTANGLE: <div>
HTML-RECTANGLE: <p></p>
HTML-RECTANGLE: </div>
-HTML-RECTANGLE-NOT: <h3>Returns</h3>
-HTML-RECTANGLE-NOT: <p> double The perimeter of the rectangle.</p>
+HTML-RECTANGLE: <h3>Returns</h3>
+HTML-RECTANGLE: <p> double The perimeter of the rectangle.</p>
HTML-RECTANGLE: </div>
HTML-RECTANGLE: </div>
HTML-RECTANGLE: </div>
@@ -705,8 +705,8 @@ HTML-CIRCLE: </div>
HTML-CIRCLE: <div>
HTML-CIRCLE: <p></p>
HTML-CIRCLE: </div>
-HTML-CIRCLE-NOT: <h3>Returns</h3>
-HTML-CIRCLE-NOT: <p> double The area of the circle.</p>
+HTML-CIRCLE: <h3>Returns</h3>
+HTML-CIRCLE: <p> double The area of the circle.</p>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
@@ -727,8 +727,8 @@ HTML-CIRCLE: </div>
HTML-CIRCLE: <div>
HTML-CIRCLE: <p></p>
HTML-CIRCLE: </div>
-HTML-CIRCLE-NOT: <h3>Returns</h3>
-HTML-CIRCLE-NOT: <p> double The perimeter of the circle.</p>
+HTML-CIRCLE: <h3>Returns</h3>
+HTML-CIRCLE: <p> double The perimeter of the circle.</p>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
More information about the llvm-branch-commits
mailing list