Author: Erick Velez Date: 2025-07-25T13:10:15-07:00 New Revision: 4df8f726087c68d6e654a76839c544b18e4ca70e
URL: https://github.com/llvm/llvm-project/commit/4df8f726087c68d6e654a76839c544b18e4ca70e DIFF: https://github.com/llvm/llvm-project/commit/4df8f726087c68d6e654a76839c544b18e4ca70e.diff LOG: [clang-doc] add code comments to comment template (#150648) Serializes Doxygen code comments in HTML templates. Modifies the basic-project to add a code example. Added: Modified: clang-tools-extra/clang-doc/JSONGenerator.cpp clang-tools-extra/clang-doc/assets/clang-doc-mustache.css clang-tools-extra/clang-doc/assets/comment-template.mustache clang-tools-extra/test/clang-doc/Inputs/basic-project/include/Circle.h clang-tools-extra/test/clang-doc/basic-project.mustache.test Removed: ################################################################################ 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> _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
