llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-clang-tools-extra Author: Erick Velez (evelez7) <details> <summary>Changes</summary> Comments weren't very visually distinctive in HTML. They immediately proceeded the declaration header and didn't have spacing between them. To visually organize them, they now have a thin border around them. Different comment types are also now separated by a small gap. This also allows them to be easily changed in the future. Some extraneous `<div>` tags are also removed or merged. --- Patch is 57.34 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/174541.diff 12 Files Affected: - (modified) clang-tools-extra/clang-doc/assets/clang-doc-mustache.css (+17) - (modified) clang-tools-extra/clang-doc/assets/class-template.mustache (+4-6) - (modified) clang-tools-extra/clang-doc/assets/comment-template.mustache (+34-26) - (modified) clang-tools-extra/clang-doc/assets/function-template.mustache (+2-4) - (modified) clang-tools-extra/test/clang-doc/basic-project.mustache.test (+188-206) - (modified) clang-tools-extra/test/clang-doc/comments-in-macros.cpp (+2-2) - (modified) clang-tools-extra/test/clang-doc/conversion_function.cpp (+1-1) - (modified) clang-tools-extra/test/clang-doc/json/class.cpp (+2-3) - (modified) clang-tools-extra/test/clang-doc/json/compound-constraints.cpp (+24-16) - (modified) clang-tools-extra/test/clang-doc/namespace.cpp (+17-25) - (modified) clang-tools-extra/test/clang-doc/templates.cpp (+20-31) - (modified) clang-tools-extra/test/clang-doc/typedef-alias.cpp (+3-3) ``````````diff 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 67f11f77eae61..ef3df037be46e 100644 --- a/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css +++ b/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css @@ -384,6 +384,14 @@ body, html { margin-bottom:1rem; } +.nested-delimiter-container { + margin-bottom: 1rem; +} + +.nested-delimiter-container:last-of-type { + margin-bottom: 0rem; +} + .resizer { width: 5px; cursor: col-resize; @@ -473,3 +481,12 @@ a, a:visited, a:hover, a:active { .code-block { white-space: pre-line; } + +.doc-card { + border: 3px solid rgba(0, 0, 0, 0.12); + border-radius: 10px; + background: #fff; + margin: 14px 0; + overflow: hidden; + padding: 10px; +} diff --git a/clang-tools-extra/clang-doc/assets/class-template.mustache b/clang-tools-extra/clang-doc/assets/class-template.mustache index 20510b6fd4d10..54cd5f7815db7 100644 --- a/clang-tools-extra/clang-doc/assets/class-template.mustache +++ b/clang-tools-extra/clang-doc/assets/class-template.mustache @@ -139,7 +139,7 @@ <h1 class="hero__title-large">{{TagType}} {{Name}}</h1> <p>Defined at line {{Location.LineNumber}} of file {{Location.Filename}}</p> {{#Description}} - <div class="hero__subtitle"> + <div class="doc-card"> {{>Comments}} </div> {{/Description}} @@ -182,11 +182,9 @@ {{#HasPublicFunctions}} <section id="PublicMethods" class="section-container"> <h2>Public Methods</h2> - <div> - {{#PublicFunctions}} - {{>FunctionPartial}} - {{/PublicFunctions}} - </div> + {{#PublicFunctions}} + {{>FunctionPartial}} + {{/PublicFunctions}} </section> {{/PublicFunctions}} {{#ProtectedFunction}} diff --git a/clang-tools-extra/clang-doc/assets/comment-template.mustache b/clang-tools-extra/clang-doc/assets/comment-template.mustache index 8d89cffd2c3bf..23bd1bfee4f80 100644 --- a/clang-tools-extra/clang-doc/assets/comment-template.mustache +++ b/clang-tools-extra/clang-doc/assets/comment-template.mustache @@ -6,17 +6,17 @@ This file defines templates for generating comments }} {{#BriefComments}} -<div> -{{#.}} +<div class="nested-delimiter-container"> + {{#.}} <p>{{TextComment}}</p> -{{/.}} + {{/.}} </div> {{/BriefComments}} {{#ParagraphComments}} -<div> -{{#.}} +<div class="nested-delimiter-container"> + {{#.}} <p>{{TextComment}}</p> -{{/.}} + {{/.}} </div> {{/ParagraphComments}} {{#ParagraphComment}} @@ -25,28 +25,34 @@ {{/Children}} {{/ParagraphComment}} {{#HasParamComments}} -<h3>Parameters</h3> -{{#ParamComments}} -<div> - <b>{{ParamName}}</b> {{#Explicit}}{{Direction}}{{/Explicit}} {{#Children}}{{TextComment}}{{/Children}} -</div> -{{/ParamComments}} +<div class="nested-delimiter-container"> + <h3>Parameters</h3> + {{#ParamComments}} + <div> + <b>{{ParamName}}</b> {{#Explicit}}{{Direction}}{{/Explicit}} {{#Children}}{{TextComment}}{{/Children}} + </div> + {{/ParamComments}} +</div> {{/HasParamComments}} {{#HasTParamComments}} <h3>Template Parameters</h3> {{#TParamComments}} -<div> - <b>{{ParamName}}</b> {{#Explicit}}{{Direction}}{{/Explicit}} {{#Children}}{{TextComment}}{{/Children}} -</div> +<div class="nested-delimiter-container"> + <div> + <b>{{ParamName}}</b> {{#Explicit}}{{Direction}}{{/Explicit}} {{#Children}}{{TextComment}}{{/Children}} + </div> +</div> {{/#TParamComments}} {{/HasTParamComments}} {{#HasReturnComments}} -<h3>Returns</h3> -{{#ReturnComments}} -{{#.}} -<p>{{TextComment}}</p> -{{/.}} -{{/ReturnComments}} +<div class="nested-delimiter-container"> + <h3>Returns</h3> + {{#ReturnComments}} + {{#.}} + <p>{{TextComment}}</p> + {{/.}} + {{/ReturnComments}} +</div> {{/HasReturnComments}} {{#HasCodeComments}} <h3>Code</h3> @@ -63,12 +69,14 @@ {{/CodeComments}} {{/HasCodeComments}} {{#HasThrowsComments}} -<h3>Throws</h3> -{{#ThrowsComments}} -<div> - <b>{{Exception}}</b> {{#Children}}{{TextComment}}{{/Children}} +<div class="nested-delimiter-container"> + <h3>Throws</h3> + {{#ThrowsComments}} + <div> + <b>{{Exception}}</b> {{#Children}}{{TextComment}}{{/Children}} + </div> + {{/ThrowsComments}} </div> -{{/ThrowsComments}} {{/HasThrowsComments}} {{#BlockCommandComment}} <div class="block-command-comment__command"> diff --git a/clang-tools-extra/clang-doc/assets/function-template.mustache b/clang-tools-extra/clang-doc/assets/function-template.mustache index 2692f0cd73b94..1e81f34196137 100644 --- a/clang-tools-extra/clang-doc/assets/function-template.mustache +++ b/clang-tools-extra/clang-doc/assets/function-template.mustache @@ -5,8 +5,7 @@ This file defines the template for functions/methods }} -<div class="delimiter-container"> - <div id="{{USR}}"> +<div id="{{USR}}" class="delimiter-container"> {{#Template}} <pre><code class="language-cpp code-clang-doc">template <{{#Parameters}}{{Param}}{{^End}}, {{/End}}{{/Parameters}}></code></pre> {{/Template}} @@ -14,10 +13,9 @@ <pre><code class="language-cpp code-clang-doc">{{ReturnType.QualName}} {{Name}}{{#Template}}{{#Specialization}}<{{#Parameters}}{{Param}}{{^End}}, {{/End}}{{/Parameters}}>{{/Specialization}}{{/Template}} ({{#Params}}{{Type.QualName}} {{Name}}{{^End}}, {{/End}}{{/Params}})</code></pre> {{! Function Comments }} {{#Description}} - <div> + <div class="doc-card"> {{>Comments}} </div> {{/Description}} <p>Defined at line {{Location.LineNumber}} of file {{Location.Filename}}</p> - </div> </div> 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 26e42280f3474..19fd6e784e011 100644 --- a/clang-tools-extra/test/clang-doc/basic-project.mustache.test +++ b/clang-tools-extra/test/clang-doc/basic-project.mustache.test @@ -57,11 +57,11 @@ HTML-SHAPE: <div class="content"> HTML-SHAPE: <section class="hero section-container"> HTML-SHAPE: <div class="hero__title"> HTML-SHAPE: <h1 class="hero__title-large">class Shape</h1> -HTML-SHAPE: <div class="hero__subtitle"> -HTML-SHAPE: <div> +HTML-SHAPE: <div class="doc-card"> +HTML-SHAPE: <div class="nested-delimiter-container"> HTML-SHAPE: <p> Abstract base class for shapes.</p> HTML-SHAPE: </div> -HTML-SHAPE: <div> +HTML-SHAPE: <div class="nested-delimiter-container"> HTML-SHAPE: <p> Provides a common interface for different types of shapes.</p> HTML-SHAPE: </div> HTML-SHAPE: </div> @@ -69,42 +69,38 @@ HTML-SHAPE: </div> HTML-SHAPE: </section> HTML-SHAPE: <section id="PublicMethods" class="section-container"> HTML-SHAPE: <h2>Public Methods</h2> -HTML-SHAPE: <div> -HTML-SHAPE: <div class="delimiter-container"> -HTML-SHAPE: <div id="{{([0-9A-F]{40})}}"> +HTML-SHAPE: <div id="{{([0-9A-F]{40})}}" class="delimiter-container"> HTML-SHAPE: <pre><code class="language-cpp code-clang-doc">double area ()</code></pre> -HTML-SHAPE: <div> -HTML-SHAPE: <div> +HTML-SHAPE: <div class="doc-card"> +HTML-SHAPE: <div class="nested-delimiter-container"> HTML-SHAPE: <p> Calculates the area of the shape.</p> HTML-SHAPE: </div> -HTML-SHAPE: <h3>Returns</h3> -HTML-SHAPE: <p> double The area of the shape.</p> +HTML-SHAPE: <div class="nested-delimiter-container"> +HTML-SHAPE: <h3>Returns</h3> +HTML-SHAPE: <p> double The area of the shape.</p> +HTML-SHAPE: </div> HTML-SHAPE: </div> HTML-SHAPE: </div> -HTML-SHAPE: </div> -HTML-SHAPE: <div class="delimiter-container"> -HTML-SHAPE: <div id="{{([0-9A-F]{40})}}"> +HTML-SHAPE: <div id="{{([0-9A-F]{40})}}" class="delimiter-container"> HTML-SHAPE: <pre><code class="language-cpp code-clang-doc">double perimeter ()</code></pre> -HTML-SHAPE: <div> -HTML-SHAPE: <div> +HTML-SHAPE: <div class="doc-card"> +HTML-SHAPE: <div class="nested-delimiter-container"> HTML-SHAPE: <p> Calculates the perimeter of the shape.</p> HTML-SHAPE: </div> -HTML-SHAPE: <h3>Returns</h3> -HTML-SHAPE: <p> double The perimeter of the shape.</p> +HTML-SHAPE: <div class="nested-delimiter-container"> +HTML-SHAPE: <h3>Returns</h3> +HTML-SHAPE: <p> double The perimeter of the shape.</p> +HTML-SHAPE: </div> HTML-SHAPE: </div> HTML-SHAPE: </div> -HTML-SHAPE: </div> -HTML-SHAPE: <div class="delimiter-container"> -HTML-SHAPE: <div id="{{([0-9A-F]{40})}}"> +HTML-SHAPE: <div id="{{([0-9A-F]{40})}}" class="delimiter-container"> HTML-SHAPE: <pre><code class="language-cpp code-clang-doc">void ~Shape ()</code></pre> -HTML-SHAPE: <div> -HTML-SHAPE: <div> +HTML-SHAPE: <div class="doc-card"> +HTML-SHAPE: <div class="nested-delimiter-container"> HTML-SHAPE: <p> Virtual destructor.</p> HTML-SHAPE: </div> HTML-SHAPE: </div> HTML-SHAPE: </div> -HTML-SHAPE: </div> -HTML-SHAPE: </div> HTML-SHAPE: </section> HTML-SHAPE: </div> HTML-SHAPE: </div> @@ -181,11 +177,11 @@ HTML-CALC: <div class="content"> HTML-CALC: <section class="hero section-container"> HTML-CALC: <div class="hero__title"> HTML-CALC: <h1 class="hero__title-large">class Calculator</h1> -HTML-CALC: <div class="hero__subtitle"> -HTML-CALC: <div> +HTML-CALC: <div class="doc-card"> +HTML-CALC: <div class="nested-delimiter-container"> HTML-CALC: <p> A simple calculator class.</p> HTML-CALC: </div> -HTML-CALC: <div> +HTML-CALC: <div class="nested-delimiter-container"> HTML-CALC: <p> Provides basic arithmetic operations.</p> HTML-CALC: </div> HTML-CALC: </div> @@ -204,115 +200,117 @@ HTML-CALC: </div> HTML-CALC: </section> HTML-CALC: <section id="PublicMethods" class="section-container"> HTML-CALC: <h2>Public Methods</h2> -HTML-CALC: <div> -HTML-CALC: <div class="delimiter-container"> -HTML-CALC: <div id="{{([0-9A-F]{40})}}"> -HTML-CALC: <pre><code class="language-cpp code-clang-doc">int add (int a, int b)</code></pre> +HTML-CALC: <div id="{{([0-9A-F]{40})}}" class="delimiter-container"> +HTML-CALC: <pre><code class="language-cpp code-clang-doc">int add (int a, int b)</code></pre> +HTML-CALC: <div class="doc-card"> +HTML-CALC: <div class="nested-delimiter-container"> +HTML-CALC: <p> Adds two integers.</p> +HTML-CALC: </div> +HTML-CALC: <div class="nested-delimiter-container"> +HTML-CALC: <h3>Parameters</h3> HTML-CALC: <div> -HTML-CALC: <div> -HTML-CALC: <p> Adds two integers.</p> -HTML-CALC: </div> -HTML-CALC: <h3>Parameters</h3> -HTML-CALC: <div> -HTML-CALC: <b>a</b> First integer. -HTML-CALC: </div> -HTML-CALC: <div> -HTML-CALC: <b>b</b> Second integer. -HTML-CALC: </div> -HTML-CALC: <h3>Returns</h3> -HTML-CALC: <p> int The sum of a and b.</p> +HTML-CALC: <b>a</b> First integer. HTML-CALC: </div> +HTML-CALC: <div> +HTML-CALC: <b>b</b> Second integer. +HTML-CALC: </div> +HTML-CALC: </div> +HTML-CALC: <div class="nested-delimiter-container"> +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 class="delimiter-container"> -HTML-CALC: <div id="{{([0-9A-F]{40})}}"> -HTML-CALC: <pre><code class="language-cpp code-clang-doc">int subtract (int a, int b)</code></pre> +HTML-CALC: </div> +HTML-CALC: <div id="{{([0-9A-F]{40})}}" class="delimiter-container"> +HTML-CALC: <pre><code class="language-cpp code-clang-doc">int subtract (int a, int b)</code></pre> +HTML-CALC: <div class="doc-card"> +HTML-CALC: <div class="nested-delimiter-container"> +HTML-CALC: <p> Subtracts the second integer from the first.</p> +HTML-CALC: </div> +HTML-CALC: <div class="nested-delimiter-container"> +HTML-CALC: <h3>Parameters</h3> HTML-CALC: <div> -HTML-CALC: <div> -HTML-CALC: <p> Subtracts the second integer from the first.</p> -HTML-CALC: </div> -HTML-CALC: <h3>Parameters</h3> -HTML-CALC: <div> -HTML-CALC: <b>a</b> First integer. -HTML-CALC: </div> -HTML-CALC: <div> -HTML-CALC: <b>b</b> Second integer. -HTML-CALC: </div> -HTML-CALC: <h3>Returns</h3> -HTML-CALC: <p> int The result of a - b.</p> +HTML-CALC: <b>a</b> First integer. +HTML-CALC: </div> +HTML-CALC: <div> +HTML-CALC: <b>b</b> Second integer. HTML-CALC: </div> HTML-CALC: </div> +HTML-CALC: <div class="nested-delimiter-container"> +HTML-CALC: <h3>Returns</h3> +HTML-CALC: <p> int The result of a - b.</p> +HTML-CALC: </div> HTML-CALC: </div> -HTML-CALC: <div class="delimiter-container"> -HTML-CALC: <div id="{{([0-9A-F]{40})}}"> -HTML-CALC: <pre><code class="language-cpp code-clang-doc">int multiply (int a, int b)</code></pre> +HTML-CALC: </div> +HTML-CALC: <div id="{{([0-9A-F]{40})}}" class="delimiter-container"> +HTML-CALC: <pre><code class="language-cpp code-clang-doc">int multiply (int a, int b)</code></pre> +HTML-CALC: <div class="doc-card"> +HTML-CALC: <div class="nested-delimiter-container"> +HTML-CALC: <p> Multiplies two integers.</p> +HTML-CALC: </div> +HTML-CALC: <div class="nested-delimiter-container"> +HTML-CALC: <h3>Parameters</h3> +HTML-CALC: <div> +HTML-CALC: <b>a</b> First integer. +HTML-CALC: </div> HTML-CALC: <div> -HTML-CALC: <div> -HTML-CALC: <p> Multiplies two integers.</p> -HTML-CALC: </div> -HTML-CALC: <h3>Parameters</h3> -HTML-CALC: <div> -HTML-CALC: <b>a</b> First integer. -HTML-CALC: </div> -HTML-CALC: <div> -HTML-CALC: <b>b</b> Second integer. -HTML-CALC: </div> -HTML-CALC: <h3>Returns</h3> -HTML-CALC: <p> int The product of a and b.</p> +HTML-CALC: <b>b</b> Second integer. HTML-CALC: </div> HTML-CALC: </div> +HTML-CALC: <div class="nested-delimiter-container"> +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 class="delimiter-container"> -HTML-CALC: <div id="{{([0-9A-F]{40})}}"> -HTML-CALC: <pre><code class="language-cpp code-clang-doc">double divide (int a, int b)</code></pre> +HTML-CALC: </div> +HTML-CALC: <div id="{{([0-9A-F]{40})}}" class="delimiter-container"> +HTML-CALC: <pre><code class="language-cpp code-clang-doc">double divide (int a, int b)</code></pre> +HTML-CALC: <div class="doc-card"> +HTML-CALC: <div class="nested-delimiter-container"> +HTML-CALC: <p> Divides the first integer by the second.</p> +HTML-CALC: </div> +HTML-CALC: <div class="nested-delimiter-container"> +HTML-CALC: <h3>Parameters</h3> +HTML-CALC: <div> +HTML-CALC: <b>a</b> First integer. +HTML-CALC: </div> HTML-CALC: <div> -HTML-CALC: <div> -HTML-CALC: <p> Divides the first integer by the ... [truncated] `````````` </details> https://github.com/llvm/llvm-project/pull/174541 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
