[llvm-branch-commits] [clang-tools-extra] [clang-doc] add code comments to comment template (PR #150648)
Erick Velez via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Fri Jul 25 11:18:33 PDT 2025
https://github.com/evelez7 updated https://github.com/llvm/llvm-project/pull/150648
>From 2101340494a046e3472d7a6d2cf08b23416b84cc Mon Sep 17 00:00:00 2001
From: Erick Velez <erickvelez7 at gmail.com>
Date: Wed, 23 Jul 2025 12:49:01 -0700
Subject: [PATCH 1/2] [clang-doc] precommit code comments
---
.../test/clang-doc/basic-project.mustache.test | 9 +++++++++
1 file changed, 9 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 2c87fe2533195..7a81c95b7194d 100644
--- a/clang-tools-extra/test/clang-doc/basic-project.mustache.test
+++ b/clang-tools-extra/test/clang-doc/basic-project.mustache.test
@@ -729,6 +729,15 @@ HTML-CIRCLE: <p></p>
HTML-CIRCLE: </div>
HTML-CIRCLE: <h3>Returns</h3>
HTML-CIRCLE: <p> double The perimeter of the circle.</p>
+HTML-CIRCLE-NOT: <h3>Code</h3>
+HTML-CIRCLE-NOT: <div>
+HTML-CIRCLE-NOT: <pre class="code-block">
+HTML-CIRCLE-NOT: <code>
+HTML-CIRCLE-NOT: Circle circle(5.0);
+HTML-CIRCLE-NOT: double perimeter = circle.perimeter();
+HTML-CIRCLE-NOT: </code>
+HTML-CIRCLE-NOT: </pre>
+HTML-CIRCLE-NOT: </div>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
>From e8795d0285332a268592323693710ed7005c7e2f Mon Sep 17 00:00:00 2001
From: Erick Velez <erickvelez7 at gmail.com>
Date: Wed, 23 Jul 2025 12:47:04 -0700
Subject: [PATCH 2/2] [clang-doc] add code comments to comment template
Serializes Doxygen code comments in HTML templates. Modifies the
basic-project to add a code example.
---
clang-tools-extra/clang-doc/JSONGenerator.cpp | 24 +++++++++++++------
.../clang-doc/assets/clang-doc-mustache.css | 4 ++++
.../assets/comment-template.mustache | 14 +++++++++++
.../Inputs/basic-project/include/Circle.h | 4 ++++
.../clang-doc/basic-project.mustache.test | 18 +++++++-------
5 files changed, 48 insertions(+), 16 deletions(-)
diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index cae1a686266c6..599b381cea60d 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp
@@ -103,6 +103,18 @@ static json::Value extractTextComments(Object *ParagraphComment) {
return *ParagraphComment->get("Children");
}
+static json::Value extractVerbatimComments(json::Array VerbatimLines) {
+ json::Value TextArray = json::Array();
+ auto &TextArrayRef = *TextArray.getAsArray();
+ for (auto &Line : VerbatimLines)
+ TextArrayRef.push_back(*Line.getAsObject()
+ ->get("VerbatimBlockLineComment")
+ ->getAsObject()
+ ->get("Text"));
+
+ return TextArray;
+}
+
static Object serializeComment(const CommentInfo &I, Object &Description) {
// taken from PR #142273
Object Obj = Object();
@@ -157,13 +169,11 @@ static Object serializeComment(const CommentInfo &I, Object &Description) {
}
case CommentKind::CK_VerbatimBlockComment: {
- Child.insert({"Text", I.Text});
- if (!I.CloseName.empty())
- Child.insert({"CloseName", I.CloseName});
- Child.insert({"Children", ChildArr});
- if (I.CloseName == "endcode")
- insertComment(Description, ChildVal, "CodeComments");
- else if (I.CloseName == "endverbatim")
+ if (I.CloseName == "endcode") {
+ // We don't support \code language specification
+ auto TextCommentsArray = extractVerbatimComments(CARef);
+ insertComment(Description, TextCommentsArray, "CodeComments");
+ } else if (I.CloseName == "endverbatim")
insertComment(Description, ChildVal, "VerbatimComments");
return Obj;
}
diff --git a/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css b/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css
index a885a36cb4a3d..e555ee7c370f7 100644
--- a/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css
+++ b/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css
@@ -469,3 +469,7 @@ a, a:visited, a:hover, a:active {
text-decoration: none;
color: inherit;
}
+
+.code-block {
+ white-space: pre-line;
+}
diff --git a/clang-tools-extra/clang-doc/assets/comment-template.mustache b/clang-tools-extra/clang-doc/assets/comment-template.mustache
index 89c48d26278c0..4e38e5fb92d18 100644
--- a/clang-tools-extra/clang-doc/assets/comment-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/comment-template.mustache
@@ -40,6 +40,20 @@
{{/.}}
{{/ReturnComments}}
{{/HasReturnComments}}
+{{#HasCodeComments}}
+ <h3>Code</h3>
+ {{#CodeComments}}
+ <div>
+ <pre class="code-block">
+ <code>
+ {{#.}}
+ {{.}}
+ {{/.}}
+ </code>
+ </pre>
+ </div>
+ {{/CodeComments}}
+{{/HasCodeComments}}
{{#BlockCommandComment}}
<div class="block-command-comment__command">
<div class="block-command-command">
diff --git a/clang-tools-extra/test/clang-doc/Inputs/basic-project/include/Circle.h b/clang-tools-extra/test/clang-doc/Inputs/basic-project/include/Circle.h
index 7bee3ffa92539..74bffcdec993b 100644
--- a/clang-tools-extra/test/clang-doc/Inputs/basic-project/include/Circle.h
+++ b/clang-tools-extra/test/clang-doc/Inputs/basic-project/include/Circle.h
@@ -26,6 +26,10 @@ class Circle : public Shape {
/**
* @brief Calculates the perimeter of the circle.
*
+ * @code
+ * Circle circle(5.0);
+ * double perimeter = circle.perimeter();
+ * @endcode
* @return double The perimeter of the circle.
*/
double perimeter() const override;
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 7a81c95b7194d..e2d9da60183fa 100644
--- a/clang-tools-extra/test/clang-doc/basic-project.mustache.test
+++ b/clang-tools-extra/test/clang-doc/basic-project.mustache.test
@@ -729,15 +729,15 @@ HTML-CIRCLE: <p></p>
HTML-CIRCLE: </div>
HTML-CIRCLE: <h3>Returns</h3>
HTML-CIRCLE: <p> double The perimeter of the circle.</p>
-HTML-CIRCLE-NOT: <h3>Code</h3>
-HTML-CIRCLE-NOT: <div>
-HTML-CIRCLE-NOT: <pre class="code-block">
-HTML-CIRCLE-NOT: <code>
-HTML-CIRCLE-NOT: Circle circle(5.0);
-HTML-CIRCLE-NOT: double perimeter = circle.perimeter();
-HTML-CIRCLE-NOT: </code>
-HTML-CIRCLE-NOT: </pre>
-HTML-CIRCLE-NOT: </div>
+HTML-CIRCLE: <h3>Code</h3>
+HTML-CIRCLE: <div>
+HTML-CIRCLE: <pre class="code-block">
+HTML-CIRCLE: <code>
+HTML-CIRCLE: Circle circle(5.0);
+HTML-CIRCLE: double perimeter = circle.perimeter();
+HTML-CIRCLE: </code>
+HTML-CIRCLE: </pre>
+HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
HTML-CIRCLE: </div>
More information about the llvm-branch-commits
mailing list