[clang-doc] add throws comments to comment template

[evelez7]

Serialize throw Doxygen comments for exceptions. Accepts both \throw and
\throws.

[evelez7]

• [clang-doc] add throws comments to comment template #150649 👈 (View in Graphite)
• [clang-doc] add code comments to comment template #150648
• [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

Serialize throw Doxygen comments for exceptions. Accepts both \throw and
\throws.

---

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

2 Files Affected:

• (modified) clang-tools-extra/clang-doc/JSONGenerator.cpp (+7)
• (modified) clang-tools-extra/clang-doc/assets/comment-template.mustache (+8)

diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index 599b381cea60d..2db6451259f60 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp
@@ -140,6 +140,13 @@ static Object serializeComment(const CommentInfo &I, Object &Description) {
       insertComment(Description, TextCommentsArray, "BriefComments");
     else if (I.Name == "return")
       insertComment(Description, TextCommentsArray, "ReturnComments");
+    else if (I.Name == "throws" || I.Name == "throw") {
+      json::Value ThrowsVal = Object();
+      auto &ThrowsObj = *ThrowsVal.getAsObject();
+      ThrowsObj["Exception"] = I.Args.front();
+      ThrowsObj["Children"] = TextCommentsArray;
+      insertComment(Description, ThrowsVal, "ThrowsComments");
+    }
     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 4e38e5fb92d18..60a4c70ec0dc4 100644
--- a/clang-tools-extra/clang-doc/assets/comment-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/comment-template.mustache
@@ -54,6 +54,14 @@
     </div>
     {{/CodeComments}}
 {{/HasCodeComments}}
+{{#HasThrowsComments}}
+    <h3>Throws</h3>
+    {{#ThrowsComments}}
+    <div>
+        <b>{{ThrowName}}</b> {{#Children}}{{>Comments}}{{/Children}}
+    </div>
+    {{/ThrowsComments}}
+{{/HasThrowsComments}}
 {{#BlockCommandComment}}
     <div class="block-command-comment__command">
         <div class="block-command-command">

[evelez7]

Think I lost track of this during GSoC submission. Should still be valid.

[ilovepi]

LGTM. It'd be nice if that HTML output looked sane, but if the tests still pass, its probably fine.

[evelez7]

The extra div isn't just present in the throws comments, it's present in the param comments as well. Here's an updated link for the output of this PR, and this class has param and throws comments: https://erickvelez.com/clang-doc-mustache-output/pr150649/GlobalNamespace/_ZTV10Calculator.html

What these two have in common is that they recursively call the comment partial to render the text comments.

llvm-project/clang-tools-extra/clang-doc/assets/comment-template.mustache

Line 31 in 6429549

<b>{{ParamName}}</b> {{#Explicit}}{{Direction}}{{/Explicit}} {{#Children}}{{>Comments}}{{/Children}}

There's no <div> on this line, so I'm not sure how one is appearing even if there is a missing placeholder data.

[ilovepi]

The extra div isn't just present in the throws comments, it's present in the param comments as well. Here's an updated link for the output of this PR, and this class has param and throws comments: https://erickvelez.com/clang-doc-mustache-output/pr150649/GlobalNamespace/_ZTV10Calculator.html

What these two have in common is that they recursively call the comment partial to render the text comments.

llvm-project/clang-tools-extra/clang-doc/assets/comment-template.mustache

Line 31 in 6429549

<b>{{ParamName}}</b> {{#Explicit}}{{Direction}}{{/Explicit}} {{#Children}}{{>Comments}}{{/Children}}

There's no <div> on this line, so I'm not sure how one is appearing even if there is a missing placeholder data.

So what seems to be happening is that the div's aren't mismatched. I took the raw html from that link and threw it into a formatter. I think the fact that that's only the FileCheck output and matching is kind of fuzzy is what's going on. We're not using CHECK-NEXT: patterns, so its not like we notice if the the closing tags are generated or not.

[ilovepi]

As for why those dive are showing up, I'd guess one of the internal partials for paragraph comment or something is gettting matched when we process the children and you end up w/ more <div></div> tags for the partials. Could be something is strange w/ the partial expansion though, and it gets rendered in an odd way.

[evelez7]

I found the issue with the <div>. It's actually behaving correctly according to our implementation. The partial begins rendering on the line that it's called, so when the partial is called and matches with {{#TextComment}} on comment-template.mustache:77

llvm-project/clang-tools-extra/clang-doc/assets/comment-template.mustache

Line 69 in 321a97e

{{#TextComment}}

the <div> is added on the first line, then the rest of the partial is rendered on newlines. So, I was misusing it thinking that the text would be rendered on the same line. Fixed that. That means I should be able to fix the other weird whitespace stuff.

Also yes, the wrong placeholder was being named for the exception. Updated the link to verify: https://erickvelez.com/clang-doc-mustache-output/pr150649/GlobalNamespace/_ZTV10Calculator.html

[ilovepi]

Thanks for running that down. This looks great now.

[evelez7]

Merge activity

• Nov 15, 6:26 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Nov 15, 6:28 PM UTC: @evelez7 merged this pull request with Graphite.