[clang-doc] Fix whitespace issues in Mustache basic test #168491
Merged
+402
−506
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
I found that the issues we've been seeing in the HTML whitespace/alignment are due to partials inserting their own whitespace and calling partials on indented lines or lines containing text already. This patch gets rid of unnecessary whitespace in the comment and function partials so that they are properly indented when inserted.
Member
|
@llvm/pr-subscribers-clang-tools-extra Author: Erick Velez (evelez7) ChangesI found that the issues we've been seeing in the HTML Patch is 48.94 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/168491.diff 4 Files Affected:
diff --git a/clang-tools-extra/clang-doc/assets/class-template.mustache b/clang-tools-extra/clang-doc/assets/class-template.mustache
index a320a938a91ff..8eb28f33e65f6 100644
--- a/clang-tools-extra/clang-doc/assets/class-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/class-template.mustache
@@ -174,7 +174,7 @@
<h2>Public Methods</h2>
<div>
{{#PublicFunctions}}
-{{>FunctionPartial}}
+ {{>FunctionPartial}}
{{/PublicFunctions}}
</div>
</section>
diff --git a/clang-tools-extra/clang-doc/assets/comment-template.mustache b/clang-tools-extra/clang-doc/assets/comment-template.mustache
index d374c715296d0..1f40333cfd4b2 100644
--- a/clang-tools-extra/clang-doc/assets/comment-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/comment-template.mustache
@@ -6,61 +6,61 @@
This file defines templates for generating comments
}}
{{#BriefComments}}
- <div>
- {{#.}}
- <p>{{TextComment}}</p>
- {{/.}}
- </div>
+<div>
+{{#.}}
+ <p>{{TextComment}}</p>
+{{/.}}
+</div>
{{/BriefComments}}
{{#ParagraphComments}}
- <div>
- {{#.}}
- <p>{{TextComment}}</p>
- {{/.}}
- </div>
+<div>
+{{#.}}
+ <p>{{TextComment}}</p>
+{{/.}}
+</div>
{{/ParagraphComments}}
{{#ParagraphComment}}
- {{#Children}}
- {{>Comments}}
- {{/Children}}
+{{#Children}}
+{{TextComment}}
+{{/Children}}
{{/ParagraphComment}}
{{#HasParamComments}}
- <h3>Parameters</h3>
- {{#ParamComments}}
- <div>
- <b>{{ParamName}}</b> {{#Explicit}}{{Direction}}{{/Explicit}} {{#Children}}{{>Comments}}{{/Children}}
- </div>
- {{/ParamComments}}
+<h3>Parameters</h3>
+{{#ParamComments}}
+<div>
+ <b>{{ParamName}}</b> {{#Explicit}}{{Direction}}{{/Explicit}} {{#Children}}{{TextComment}}{{/Children}}
+</div>
+{{/ParamComments}}
{{/HasParamComments}}
{{#HasReturnComments}}
- <h3>Returns</h3>
- {{#ReturnComments}}
- {{#.}}
- <p>{{TextComment}}</p>
- {{/.}}
- {{/ReturnComments}}
+<h3>Returns</h3>
+{{#ReturnComments}}
+{{#.}}
+<p>{{TextComment}}</p>
+{{/.}}
+{{/ReturnComments}}
{{/HasReturnComments}}
{{#HasCodeComments}}
- <h3>Code</h3>
- {{#CodeComments}}
- <div>
- <pre class="code-block">
- <code>
- {{#.}}
+<h3>Code</h3>
+{{#CodeComments}}
+<div>
+ <pre class="code-block">
+ <code>
+ {{#.}}
{{.}}
- {{/.}}
- </code>
- </pre>
- </div>
- {{/CodeComments}}
+ {{/.}}
+ </code>
+ </pre>
+</div>
+{{/CodeComments}}
{{/HasCodeComments}}
{{#HasThrowsComments}}
- <h3>Throws</h3>
- {{#ThrowsComments}}
- <div>
- <b>{{Exception}}</b> {{#Children}}{{TextComment}}{{/Children}}
- </div>
- {{/ThrowsComments}}
+<h3>Throws</h3>
+{{#ThrowsComments}}
+<div>
+ <b>{{Exception}}</b> {{#Children}}{{TextComment}}{{/Children}}
+</div>
+{{/ThrowsComments}}
{{/HasThrowsComments}}
{{#BlockCommandComment}}
<div class="block-command-comment__command">
@@ -74,8 +74,3 @@
</div>
</div>
{{/BlockCommandComment}}
-{{#TextComment}}
- <div>
- <p>{{TextComment}}</p>
- </div>
-{{/TextComment}}
diff --git a/clang-tools-extra/clang-doc/assets/function-template.mustache b/clang-tools-extra/clang-doc/assets/function-template.mustache
index 2510a4de2cd68..dc787bf0c8694 100644
--- a/clang-tools-extra/clang-doc/assets/function-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/function-template.mustache
@@ -8,11 +8,7 @@
<div class="delimiter-container">
<div id="{{USR}}">
{{! Function Prototype }}
- <pre>
- <code class="language-cpp code-clang-doc">
-{{ReturnType.Name}} {{Name}} ({{#Params}}{{^End}}{{Type}} {{Name}}, {{/End}}{{#End}}{{Type}} {{Name}}{{/End}}{{/Params}})
- </code>
- </pre>
+ <pre><code class="language-cpp code-clang-doc">{{ReturnType.Name}} {{Name}} ({{#Params}}{{^End}}{{Type}} {{Name}}, {{/End}}{{#End}}{{Type}} {{Name}}{{/End}}{{/Params}})</code></pre>
{{! Function Comments }}
{{#Description}}
<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 a3041336327e8..9f7de6e689313 100644
--- a/clang-tools-extra/test/clang-doc/basic-project.mustache.test
+++ b/clang-tools-extra/test/clang-doc/basic-project.mustache.test
@@ -60,84 +60,72 @@ 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: <p> Abstract base class for shapes.</p>
-HTML-SHAPE: </div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p></p>
-HTML-SHAPE: </div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p> Provides a common interface for different types of shapes.</p>
-HTML-SHAPE: </div>
-HTML-SHAPE: </div>
+HTML-SHAPE: <div class="hero__subtitle">
+HTML-SHAPE: <div>
+HTML-SHAPE: <p> Abstract base class for shapes.</p>
+HTML-SHAPE: </div>
+HTML-SHAPE: <div>
+HTML-SHAPE: <p></p>
+HTML-SHAPE: </div>
+HTML-SHAPE: <div>
+HTML-SHAPE: <p> Provides a common interface for different types of shapes.</p>
+HTML-SHAPE: </div>
+HTML-SHAPE: </div>
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: <pre>
-HTML-SHAPE: <code class="language-cpp code-clang-doc">
-HTML-SHAPE: double area ()
-HTML-SHAPE: </code>
-HTML-SHAPE: </pre>
-HTML-SHAPE: <div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p> Calculates the area of the shape.</p>
-HTML-SHAPE: </div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p></p>
-HTML-SHAPE: </div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p></p>
-HTML-SHAPE: </div>
-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 class="delimiter-container">
-HTML-SHAPE: <div id="{{([0-9A-F]{40})}}">
-HTML-SHAPE: <pre>
-HTML-SHAPE: <code class="language-cpp code-clang-doc">
-HTML-SHAPE: double perimeter ()
-HTML-SHAPE: </code>
-HTML-SHAPE: </pre>
-HTML-SHAPE: <div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p> Calculates the perimeter of the shape.</p>
-HTML-SHAPE: </div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p></p>
-HTML-SHAPE: </div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p></p>
-HTML-SHAPE: </div>
-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 class="delimiter-container">
-HTML-SHAPE: <div id="{{([0-9A-F]{40})}}">
-HTML-SHAPE: <pre>
-HTML-SHAPE: <code class="language-cpp code-clang-doc">
-HTML-SHAPE: void ~Shape ()
-HTML-SHAPE: </code>
-HTML-SHAPE: </pre>
-HTML-SHAPE: <div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p> Virtual destructor.</p>
-HTML-SHAPE: </div>
-HTML-SHAPE: <div>
-HTML-SHAPE: <p></p>
-HTML-SHAPE: </div>
-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: <pre><code class="language-cpp code-clang-doc">double area ()</code></pre>
+HTML-SHAPE: <div>
+HTML-SHAPE: <div>
+HTML-SHAPE: <p> Calculates the area of the shape.</p>
+HTML-SHAPE: </div>
+HTML-SHAPE: <div>
+HTML-SHAPE: <p></p>
+HTML-SHAPE: </div>
+HTML-SHAPE: <div>
+HTML-SHAPE: <p></p>
+HTML-SHAPE: </div>
+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 class="delimiter-container">
+HTML-SHAPE: <div id="{{([0-9A-F]{40})}}">
+HTML-SHAPE: <pre><code class="language-cpp code-clang-doc">double perimeter ()</code></pre>
+HTML-SHAPE: <div>
+HTML-SHAPE: <div>
+HTML-SHAPE: <p> Calculates the perimeter of the shape.</p>
+HTML-SHAPE: </div>
+HTML-SHAPE: <div>
+HTML-SHAPE: <p></p>
+HTML-SHAPE: </div>
+HTML-SHAPE: <div>
+HTML-SHAPE: <p></p>
+HTML-SHAPE: </div>
+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 class="delimiter-container">
+HTML-SHAPE: <div id="{{([0-9A-F]{40})}}">
+HTML-SHAPE: <pre><code class="language-cpp code-clang-doc">void ~Shape ()</code></pre>
+HTML-SHAPE: <div>
+HTML-SHAPE: <div>
+HTML-SHAPE: <p> Virtual destructor.</p>
+HTML-SHAPE: </div>
+HTML-SHAPE: <div>
+HTML-SHAPE: <p></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>
@@ -217,219 +205,164 @@ 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>
-HTML-CALC: <p> A simple calculator class.</p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p> Provides basic arithmetic operations.</p>
-HTML-CALC: </div>
-HTML-CALC: </div>
+HTML-CALC: <div class="hero__subtitle">
+HTML-CALC: <div>
+HTML-CALC: <p> A simple calculator class.</p>
+HTML-CALC: </div>
+HTML-CALC: <div>
+HTML-CALC: <p></p>
+HTML-CALC: </div>
+HTML-CALC: <div>
+HTML-CALC: <p> Provides basic arithmetic operations.</p>
+HTML-CALC: </div>
+HTML-CALC: </div>
HTML-CALC: </div>
HTML-CALC: </section>
HTML-CALC: <section id="PublicMembers" class="section-container">
HTML-CALC: <h2>Public Members</h2>
HTML-CALC: <div>
HTML-CALC: <div id="public_val" class="delimiter-container">
-HTML-CALC: <pre>
-HTML-CALC: <code class="language-cpp code-clang-doc" >int public_val</code>
-HTML-CALC: </pre>
+HTML-CALC: <pre><code class="language-cpp code-clang-doc" >int public_val</code></pre>
HTML-CALC: </div>
HTML-CALC: <div id="static_val" class="delimiter-container">
-HTML-CALC: <pre>
-HTML-CALC: <code class="language-cpp code-clang-doc" >const int static_val</code>
-HTML-CALC: </pre>
+HTML-CALC: <pre><code class="language-cpp code-clang-doc" >const int static_val</code></pre>
HTML-CALC: </div>
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>
-HTML-CALC: <code class="language-cpp code-clang-doc">
-HTML-CALC: int add (int a, int b)
-HTML-CALC: </code>
-HTML-CALC: </pre>
-HTML-CALC: <div>
-HTML-CALC: <div>
-HTML-CALC: <p> Adds two integers.</p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <h3>Parameters</h3>
-HTML-CALC: <div>
-HTML-CALC: <b>a</b> <div>
-HTML-CALC: <p> First integer.</p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <b>b</b> <div>
-HTML-CALC: <p> Second integer.</p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: </div>
-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>
-HTML-CALC: <div class="delimiter-container">
-HTML-CALC: <div id="{{([0-9A-F]{40})}}">
-HTML-CALC: <pre>
-HTML-CALC: <code class="language-cpp code-clang-doc">
-HTML-CALC: int subtract (int a, int b)
-HTML-CALC: </code>
-HTML-CALC: </pre>
-HTML-CALC: <div>
-HTML-CALC: <div>
-HTML-CALC: <p> Subtracts the second integer from the first.</p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <h3>Returns</h3>
-HTML-CALC: <p> int The result of a - b.</p>
-HTML-CALC: </div>
-HTML-CALC: </div>
-HTML-CALC: </div>
-HTML-CALC: <div class="delimiter-container">
-HTML-CALC: <div id="{{([0-9A-F]{40})}}">
-HTML-CALC: <pre>
-HTML-CALC: <code class="language-cpp code-clang-doc">
-HTML-CALC: int multiply (int a, int b)
-HTML-CALC: </code>
-HTML-CALC: </pre>
-HTML-CALC: <div>
-HTML-CALC: <div>
-HTML-CALC: <p> Multiplies two integers.</p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <h3>Parameters</h3>
-HTML-CALC: <div>
-HTML-CALC: <b>a</b> <div>
-HTML-CALC: <p> First integer.</p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <b>b</b> <div>
-HTML-CALC: <p> Second integer.</p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: </div>
-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>
-HTML-CALC: <div class="delimiter-container">
-HTML-CALC: <div id="{{([0-9A-F]{40})}}">
-HTML-CALC: <pre>
-HTML-CALC: <code class="language-cpp code-clang-doc">
-HTML-CALC: double divide (int a, int b)
-HTML-CALC: </code>
-HTML-CALC: </pre>
-HTML-CALC: <div>
-HTML-CALC: <div>
-HTML-CALC: <p> Divides the first integer by the second.</p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: <h3>Parameters</h3>
-HTML-CALC: <div>
-HTML-CALC: <b>a</b> <div>
-HTML-CALC: <p> First integer.</p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <b>b</b> <div>
-HTML-CALC: <p> Second integer.</p>
-HTML-CALC: </div>
-HTML-CALC: <div>
-HTML-CALC: <p></p>
-HTML-CALC: </div>
-HTML-CALC: </div>
-HTML-CALC: <h3>Returns</h3>
-HTML-CALC: ...
[truncated]
|
Member
Author
|
Basic project output: https://erickvelez.com/clang-doc-mustache-output/pr168491/GlobalNamespace/ |
🐧 Linux x64 Test Results
|
Contributor
|
Can you check if the output changes if we just ran the templates through an HTML formatter? I threw the HTML from before your change into just a random one from a google search to see (https://www.freeformatter.com/) and it did indent the partial the way you have it, and likely some more things too. If the output is not different or looks correct, then we should probably just format them all. |
ilovepi
approved these changes
Nov 18, 2025
Member
Author
That's probably a good idea. Only thing is that we don't have tests for all of the HTML output right now, so there's nothing to currently reference whether the output is bad or not. For example, the formatter also indented |
Contributor
|
Well, arguably, if the tests still pass its OK, but that's a rather brittle assertion. #168569 may also help in that regard, since we'd just UTC all the files that break. I may look at that more seriously today if I have time. |
Member
Author
evelez7
deleted the
users/evelez7/clang-doc-fix-html-mustache-whitespace
branch
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I found that the issues we've been seeing in the HTML
whitespace/alignment are due to partials inserting their own whitespace
and calling partials on indented lines or lines containing text already.
This patch gets rid of unnecessary whitespace in the comment and
function partials so that they are properly indented when inserted.