[clang-doc] add code comments to comment template

[evelez7]

Serializes Doxygen code comments in HTML templates. Modifies the
basic-project to add a code example.

[evelez7]

• [clang-doc] add throws comments to comment template #150649
• [clang-doc] add code comments to comment template #150648 👈 (View in Graphite)
• [clang-doc] add return comments to comment template #150647
• [clang-doc] add param comments to comment template #150571
• [clang-doc] generate comments for functions #150570
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[llvmbot]

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

Author: Erick Velez (evelez7)

Changes

Serializes Doxygen code comments in HTML templates. Modifies the
basic-project to add a code example.

---

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

5 Files Affected:

• (modified) clang-tools-extra/clang-doc/JSONGenerator.cpp (+17-7)
• (modified) clang-tools-extra/clang-doc/assets/clang-doc-mustache.css (+4)
• (modified) clang-tools-extra/clang-doc/assets/comment-template.mustache (+14)
• (modified) clang-tools-extra/test/clang-doc/Inputs/basic-project/include/Circle.h (+4)
• (modified) clang-tools-extra/test/clang-doc/basic-project.mustache.test (+9)

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 2c87fe2533195..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,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:                    <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>

[graphite-app]

Merge activity

• Jul 25, 7:34 PM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.
• Jul 25, 8:03 PM UTC: Graphite rebased this pull request as part of a merge.
• Jul 25, 8:06 PM UTC: Graphite rebased this pull request as part of a merge.
• Jul 25, 8:09 PM UTC: Graphite rebased this pull request as part of a merge.