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

@@ -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>

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.

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">