From 35762dd1ecd9a5544bbcc85ab83eb6706aaf6e10 Mon Sep 17 00:00:00 2001
From: Erick Velez <erickvelez7@gmail.com>
Date: Thu, 24 Jul 2025 22:10:51 -0700
Subject: [PATCH] [clang-doc] add throws comments to comment template

Serialize throw Doxygen comments for exceptions. Accepts both \throw and
\throws.
---
 clang-tools-extra/clang-doc/JSONGenerator.cpp             | 7 +++++++
 .../clang-doc/assets/comment-template.mustache            | 8 ++++++++
 .../test/clang-doc/basic-project.mustache.test            | 4 ++++
 3 files changed, 19 insertions(+)

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">
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 e2d9da60183fa..88317393bb26c 100644
--- a/clang-tools-extra/test/clang-doc/basic-project.mustache.test
+++ b/clang-tools-extra/test/clang-doc/basic-project.mustache.test
@@ -384,6 +384,10 @@ HTML-CALC:                    </div>
 HTML-CALC:                    <h3>Returns</h3>
 HTML-CALC:                        <p> double The result of a / b.</p>
 HTML-CALC:                        <p></p>
+HTML-CALC:                    <h3>Throws</h3>
+HTML-CALC:                    <div>
+HTML-CALC:                        <b></b>     <div>
+HTML-CALC:                        <p>if b is zero.</p>
 HTML-CALC:                        </div>
 HTML-CALC:     </div>
 HTML-CALC: </div>