From 719af2337faae26c33a68ed2e424a3afa67486b2 Mon Sep 17 00:00:00 2001
From: Andrey Semashev <andrey.semashev@gmail.com>
Date: Sat, 6 Jul 2024 17:39:23 +0300
Subject: [PATCH] Fix handling of multiple exception descriptions, support free
 form description.

When there are multiple \throws entries in a function documentation, the second
and further exception names were omitted from output and a combined description
was associated with the first exception. Fix this by producing separate
paragraphs, one per exception.

Additionally, support free form exception description when the exception type
is specified as "~". In this case, the exception name is not used, and the
entry description is used to initialize the paragraph in the output.

Updated test to verify these changes.
---
 test/doxygen/autodoc.gold         |  6 +++++-
 test/doxygen/boost/example.hpp    |  3 +++
 xsl/doxygen/doxygen2boostbook.xsl | 36 ++++++++++++++++++-------------
 3 files changed, 29 insertions(+), 16 deletions(-)

diff --git a/test/doxygen/autodoc.gold b/test/doxygen/autodoc.gold
index 7ae50c8..8324a66 100644
--- a/test/doxygen/autodoc.gold
+++ b/test/doxygen/autodoc.gold
@@ -104,13 +104,17 @@ int foo2();
 <function id="doxygen.example_reference.example_8hpp_1addcdeb7a8901ec383539fabdc69b1ae1" name="namespace_func"><type>int</type><parameter name="i"><paramtype>int</paramtype><description><para>A function parameter </para></description></parameter><parameter name="j"><paramtype>int</paramtype><description><para>Another </para></description></parameter><description><para>
 
 
+
 This is a test function. <link linkend="doxygen.example_reference.classexample_1_1example">Link to class</link> <link linkend="doxygen.example_reference.structexample_1_1example__template">Link to class template</link> <note><para>This is a note.</para>
 </note>
 <formalpara><title>See Also:</title><para><link linkend="doxygen.example_reference.classexample_1_1example">example::example</link> and <link linkend="doxygen.example_reference.structexample_1_1example__template">example_template</link> </para>
 </formalpara>
 </para></description><requires><para>i &gt; j</para>
 </requires><returns><para>The answer </para>
-</returns></function>
+</returns><throws><simpara><classname>std::runtime_error</classname> Some error description </simpara>
+<simpara><classname>std::bad_alloc</classname> Memory allocation error </simpara>
+<simpara>Free form description of exception throwing </simpara>
+</throws></function>
 <function id="doxygen.example_reference.example_8hpp_1ae06fcc1d7c044252611b2ebb2b665e53" name="namespace_func_template"><type>void</type><template>
           <template-type-parameter name="TypeParameter"><purpose><para>A template parameter </para></purpose></template-type-parameter>
           <template-nontype-parameter name="NonTypeParameter"><type>int</type><purpose><para>This is a non-type template parameter </para></purpose></template-nontype-parameter>
diff --git a/test/doxygen/boost/example.hpp b/test/doxygen/boost/example.hpp
index 9b32da0..aac272d 100644
--- a/test/doxygen/boost/example.hpp
+++ b/test/doxygen/boost/example.hpp
@@ -196,6 +196,9 @@ namespace example
      * \param i A function parameter
      * \param j Another
      * \return The answer
+     * \throw std::runtime_error Some error description
+     * \throw std::bad_alloc Memory allocation error
+     * \throw ~ Free form description of exception throwing
      * \pre i > j
      *
      * This is a test function.
diff --git a/xsl/doxygen/doxygen2boostbook.xsl b/xsl/doxygen/doxygen2boostbook.xsl
index dddc90b..f93dd59 100644
--- a/xsl/doxygen/doxygen2boostbook.xsl
+++ b/xsl/doxygen/doxygen2boostbook.xsl
@@ -1804,24 +1804,30 @@
 
   <xsl:template match="parameterlist" mode="function-clauses">
     <xsl:if test="@kind='exception'">
-      <simpara>
-        <xsl:choose>
-          <xsl:when test="normalize-space(.//parametername//text())='nothrow'">
-            <xsl:text>Will not throw.</xsl:text>
-          </xsl:when>
-          <xsl:otherwise>
+      <xsl:apply-templates mode="exception.description"/>
+    </xsl:if>
+  </xsl:template>
+
+  <xsl:template match="parameteritem" mode="exception.description">
+    <simpara>
+      <xsl:choose>
+        <xsl:when test="normalize-space(./parameternamelist/parametername//text())='nothrow'">
+          <xsl:text>Will not throw.</xsl:text>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:if test="normalize-space(./parameternamelist/parametername//text())!='~'">
             <classname>
-              <xsl:value-of select=".//parametername//text()"/>
+              <xsl:value-of select="./parameternamelist/parametername//text()"/>
             </classname>
             <xsl:text> </xsl:text>
-            <xsl:apply-templates 
-              select=".//parameterdescription/para/text()
-                      |.//parameterdescription/para/*"
-              mode="passthrough"/>
-          </xsl:otherwise>
-        </xsl:choose>
-      </simpara>
-    </xsl:if>
+          </xsl:if>
+          <xsl:apply-templates
+            select="./parameterdescription/para/text()
+                    |./parameterdescription/para/*"
+            mode="passthrough"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </simpara>
   </xsl:template>
 
   <xsl:template match="type">