Skip to content

[clang-doc] add return comments to comment template #150647

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 2 commits into from
Jul 25, 2025
Merged

[clang-doc] add return comments to comment template #150647

merged 2 commits into from
Jul 25, 2025

Conversation

evelez7
Copy link
Member

@evelez7 evelez7 commented Jul 25, 2025 •
edited
Loading

Serialize return comments in HTML templates.

This was referenced Jul 25, 2025
Merged
Merged
@evelez7 Graphite App
Copy link
Member Author

evelez7 commented Jul 25, 2025 •
edited
Loading

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

This was referenced Jul 25, 2025
Open
Merged
@evelez7 evelez7 marked this pull request as ready for review July 25, 2025 16:40
@llvmbot
Copy link
Member

llvmbot commented Jul 25, 2025

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

Author: Erick Velez (evelez7)

Changes

[clang-doc] add return comments to comment template

Serialize return comments in HTML templates.

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

3 Files Affected:

  • (modified) clang-tools-extra/clang-doc/JSONGenerator.cpp (+2)
  • (modified) clang-tools-extra/clang-doc/assets/comment-template.mustache (+8)
  • (modified) clang-tools-extra/test/clang-doc/basic-project.mustache.test (+23)
diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index 5fc28406ee870..cae1a686266c6 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp
@@ -126,6 +126,8 @@ static Object serializeComment(const CommentInfo &I, Object &Description) {
     auto TextCommentsArray = extractTextComments(CARef.front().getAsObject());
     if (I.Name == "brief")
       insertComment(Description, TextCommentsArray, "BriefComments");
+    else if (I.Name == "return")
+      insertComment(Description, TextCommentsArray, "ReturnComments");
     return Obj;
   }
 
diff --git a/clang-tools-extra/clang-doc/assets/comment-template.mustache b/clang-tools-extra/clang-doc/assets/comment-template.mustache
index d55a53194ee5c..89c48d26278c0 100644
--- a/clang-tools-extra/clang-doc/assets/comment-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/comment-template.mustache
@@ -32,6 +32,14 @@
     </div> 
     {{/ParamComments}}
 {{/HasParamComments}}
+{{#HasReturnComments}}
+    <h3>Returns</h3>
+    {{#ReturnComments}}
+        {{#.}}
+        <p>{{TextComment}}</p>
+        {{/.}}
+    {{/ReturnComments}}
+{{/HasReturnComments}}
 {{#BlockCommandComment}}
     <div class="block-command-comment__command">
         <div class="block-command-command">
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 b55e0abe2cdef..2c87fe2533195 100644
--- a/clang-tools-extra/test/clang-doc/basic-project.mustache.test
+++ b/clang-tools-extra/test/clang-doc/basic-project.mustache.test
@@ -93,6 +93,8 @@ 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>
@@ -113,6 +115,8 @@ 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>
@@ -277,6 +281,8 @@ 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>
@@ -297,6 +303,8 @@ 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>
@@ -334,6 +342,8 @@ 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>
@@ -371,6 +381,9 @@ HTML-CALC:                    <div>
 HTML-CALC:                        <p></p>
 HTML-CALC:                    </div>
 HTML-CALC:                    </div>
+HTML-CALC:                    <h3>Returns</h3>
+HTML-CALC:                        <p> double The result of a / b.</p>
+HTML-CALC:                        <p></p>
 HTML-CALC:                        </div>
 HTML-CALC:     </div>
 HTML-CALC: </div>
@@ -408,6 +421,8 @@ HTML-CALC:                    <div>
 HTML-CALC:                        <p></p>
 HTML-CALC:                    </div>
 HTML-CALC:                    </div>
+HTML-CALC:                    <h3>Returns</h3>
+HTML-CALC:                        <p> The result of a % b.</p>
 HTML-CALC:                        </div>
 HTML-CALC:     </div>
 HTML-CALC: </div>
@@ -541,6 +556,8 @@ HTML-RECTANGLE:                    </div>
 HTML-RECTANGLE:                        <div>
 HTML-RECTANGLE:                        <p></p>
 HTML-RECTANGLE:                    </div>
+HTML-RECTANGLE:                    <h3>Returns</h3>
+HTML-RECTANGLE:                        <p> double The area of the rectangle.</p>
 HTML-RECTANGLE:                        </div>
 HTML-RECTANGLE:     </div>
 HTML-RECTANGLE: </div>
@@ -561,6 +578,8 @@ HTML-RECTANGLE:                    </div>
 HTML-RECTANGLE:                        <div>
 HTML-RECTANGLE:                        <p></p>
 HTML-RECTANGLE:                    </div>
+HTML-RECTANGLE:                    <h3>Returns</h3>
+HTML-RECTANGLE:                        <p> double The perimeter of the rectangle.</p>
 HTML-RECTANGLE:                        </div>
 HTML-RECTANGLE:     </div>
 HTML-RECTANGLE: </div>
@@ -686,6 +705,8 @@ HTML-CIRCLE:                    </div>
 HTML-CIRCLE:                        <div>
 HTML-CIRCLE:                        <p></p>
 HTML-CIRCLE:                    </div>
+HTML-CIRCLE:                    <h3>Returns</h3>
+HTML-CIRCLE:                        <p> double The area of the circle.</p>
 HTML-CIRCLE:                        </div>
 HTML-CIRCLE:     </div>
 HTML-CIRCLE: </div>
@@ -706,6 +727,8 @@ HTML-CIRCLE:                    </div>
 HTML-CIRCLE:                        <div>
 HTML-CIRCLE:                        <p></p>
 HTML-CIRCLE:                    </div>
+HTML-CIRCLE:                    <h3>Returns</h3>
+HTML-CIRCLE:                        <p> double The perimeter of the circle.</p>
 HTML-CIRCLE:                        </div>
 HTML-CIRCLE:     </div>
 HTML-CIRCLE: </div>

@evelez7 evelez7 requested review from ilovepi and petrhosek July 25, 2025 16:41
@evelez7 evelez7 changed the title [clang-doc] precommit return comments test [clang-doc] add return comments to comment template Jul 25, 2025
@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-param-comments branch from c6fbf4d to 158802a Compare July 25, 2025 17:42
@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-return-comments branch from f46ee3e to 6f19128 Compare July 25, 2025 17:43
@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-param-comments branch 2 times, most recently from cef7188 to 17db501 Compare July 25, 2025 18:07
Base automatically changed from users/evelez7/clang-doc-param-comments to main July 25, 2025 18:16
@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-return-comments branch 2 times, most recently from 68c10c8 to 518c754 Compare July 25, 2025 18:40
@evelez7 Graphite App
Copy link
Member Author

evelez7 commented Jul 25, 2025 •
edited
Loading

Merge activity

  • Jul 25, 6:41 PM UTC: Graphite rebased this pull request as part of a merge.
  • Jul 25, 6:47 PM UTC: Graphite rebased this pull request as part of a merge.
  • Jul 25, 6:51 PM UTC: Graphite rebased this pull request as part of a merge.
  • Jul 25, 6:59 PM UTC: Graphite rebased this pull request as part of a merge.
  • Jul 25, 7:04 PM UTC: Graphite rebased this pull request as part of a merge.
  • Jul 25, 7:09 PM UTC: Graphite rebased this pull request as part of a merge.
  • Jul 25, 7:13 PM UTC: Graphite rebased this pull request as part of a merge.
  • Jul 25, 7:16 PM UTC: Graphite rebased this pull request as part of a merge.
  • Jul 25, 7:23 PM UTC: Graphite rebased this pull request as part of a merge.
  • Jul 25, 7:26 PM UTC: Graphite rebased this pull request as part of a merge.
  • Jul 25, 7:33 PM UTC: Graphite couldn't merge this PR because it failed for an unknown reason.

@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-return-comments branch 8 times, most recently from 2905e87 to 1090ebb Compare July 25, 2025 19:22
@evelez7 evelez7 closed this Jul 25, 2025
@evelez7 evelez7 reopened this Jul 25, 2025
@evelez7 evelez7 force-pushed the users/evelez7/clang-doc-return-comments branch from 1090ebb to 7c486a6 Compare July 25, 2025 19:25
@evelez7
Copy link
Member Author

evelez7 commented Jul 25, 2025

The CI was green before I started a stack merge via Graphite. Now it's stuck in this terrible loop so I'm going to bypass the rule and force it to merge.

@boomanaiden154 Not sure if you know anything about this but maybe you can point me to someone who does. I think the newly required CI rules don't play nice with Graphite auto-merging. Graphites constantly rebases the branch when trying to merge, which will cause CI to trigger again.

@evelez7 evelez7 merged commit 63c2b8a into main Jul 25, 2025
5 of 8 checks passed
@evelez7 evelez7 deleted the users/evelez7/clang-doc-return-comments branch July 25, 2025 19:32
@boomanaiden154
Copy link
Contributor

Not sure if you know anything about this but maybe you can point me to someone who does. I think the newly required CI rules don't play nice with Graphite auto-merging. Graphites constantly rebases the branch when trying to merge, which will cause CI to trigger again.

I don't use Graphite and am definitely not familiar with the internal details of how it works. This seems like it's a Graphite problem more so than anything else though. Seems like someone should do some preliminary investigation and then contact the Graphite folks.

@boomanaiden154
Copy link
Contributor

@evelez7 Do you have more details on what exactly you did within Graphite? Did you try to merge multiple PRs in a stack or just the bottom one?

@evelez7
Copy link
Member Author

evelez7 commented Jul 25, 2025

@evelez7 Do you have more details on what exactly you did within Graphite? Did you try to merge multiple PRs in a stack or just the bottom one?

I started a stack merge of 3 PRs starting with #150570 and this was supposed to be the 2nd one. The third PR is currently waiting for CI.

I just submitted a bug report/feedback via Graphite. This seems like a pretty big problem for Graphite in LLVM so I was even wondering if merging stacks should be disabled if possible.

@ilovepi
Copy link
Contributor

ilovepi commented Jul 25, 2025

I ran into a similar problem, and Nikita had to cancel the whole thing (IIRC by closing the PR and then reopening). It was not great, so I normally just merge them one at a time now.

mahesh-attarde pushed a commit to mahesh-attarde/llvm-project that referenced this pull request Jul 28, 2025
@evelez7 @mahesh-attarde
[clang-doc] add return comments to comment template (llvm#150647)
d32da62 
Serialize return comments in HTML templates.
@boomanaiden154 boomanaiden154 mentioned this pull request Jul 29, 2025
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ilovepi ilovepi ilovepi approved these changes

@petrhosek petrhosek Awaiting requested review from petrhosek

Assignees
No one assigned
Labels
clang-tools-extra
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@evelez7 @llvmbot @boomanaiden154 @ilovepi