vovkos / doxyrest

A compiler from Doxygen XML to reStructuredText -- hence, the name. It parses XML databases generated by Doxygen and produces reStructuredText for the Python documentation generator Sphinx.
MIT License
306 stars 23 forks source link

Doxyrest is not processing/generating C++ throw statements / exceptions #56

Open ceandrade opened 1 year ago

ceandrade commented 1 year ago

Suppose we have the following class:

/**
 * \brief This is a testing class for doxyrest.
 */
class TestDoxyrest {
public:
    /**
     * \brief Sets a custom value.
     *
     * \param value a new value.
     * \throws std::runtime_error in case the value is invalid.
     */
    void setNewValue(double value);
};

Using Doxygen, we can generate the following HTML piece:

Screenshot 2023-09-27 at 11 46 38 PM

And the following XML content:

<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.9.3" xml:lang="en-US">
  <compounddef id="class_test_doxyrest" kind="class" language="C++" prot="public">
    <compoundname>TestDoxyrest</compoundname>
      <sectiondef kind="public-func">
      <memberdef kind="function" id="class_test_doxyrest_1aeebf9e659e590a27b2c42601d0b65c3b" prot="public" static="no" const="no" explicit="no" inline="no" virt="non-virtual">
        <type>void</type>
        <definition>void TestDoxyrest::setNewValue</definition>
        <argsstring>(double value)</argsstring>
        <name>setNewValue</name>
        <qualifiedname>TestDoxyrest::setNewValue</qualifiedname>
        <param>
          <type>double</type>
          <declname>value</declname>
        </param>
        <briefdescription>
<para>Sets a custom value. </para>
        </briefdescription>
        <detaileddescription>
<para><parameterlist kind="param"><parameteritem>
<parameternamelist>
<parametername>value</parametername>
</parameternamelist>
<parameterdescription>
<para>a new value. </para>
</parameterdescription>
</parameteritem>
</parameterlist>
<parameterlist kind="exception"><parameteritem>
<parameternamelist>
<parametername>std::runtime_error</parametername>
</parameternamelist>
<parameterdescription>
<para>in case the value is invalid. </para>
</parameterdescription>
</parameteritem>
</parameterlist>
</para>
        </detaileddescription>
        <inbodydescription>
        </inbodydescription>
        <location file="test_doxyrest.cpp" line="12" column="10"/>
      </memberdef>
      </sectiondef>
    <briefdescription>
<para>This is a testing class for doxyrest. </para>
    </briefdescription>
    <detaileddescription>
    </detaileddescription>
    <collaborationgraph>
      <node id="1">
        <label>TestDoxyrest</label>
        <link refid="class_test_doxyrest"/>
      </node>
    </collaborationgraph>
    <location file="test_doxyrest.cpp" line="4" column="1" bodyfile="test_doxyrest.cpp" bodystart="4" bodyend="13"/>
    <listofallmembers>
      <member refid="class_test_doxyrest_1aeebf9e659e590a27b2c42601d0b65c3b" prot="public" virt="non-virtual"><scope>TestDoxyrest</scope><name>setNewValue</name></member>
    </listofallmembers>
  </compounddef>
</doxygen>

Note that Doxygen generates a tag with kind="exception":

<parameterlist kind="exception"><parameteritem>
<parameternamelist>
<parametername>std::runtime_error</parametername>
</parameternamelist>
<parameterdescription>
<para>in case the value is invalid. </para>
</parameterdescription>
</parameteritem>
</parameterlist>

Now, Doxyrest is unable to identify kind="exception" and only adds it to the list of regular parameters. This is the RST generated by Doxyrest:

.. index:: pair: class; TestDoxyrest
.. _doxid-class_test_doxyrest:

class TestDoxyrest
==================

.. toctree::
    :hidden:

Overview
~~~~~~~~

This is a testing class for doxyrest. :ref:`More...<details-class_test_doxyrest>`

.. ref-code-block:: cpp
    :class: doxyrest-overview-code-block

    class TestDoxyrest {
    public:
        // methods

        void :ref:`setNewValue<doxid-class_test_doxyrest_1aeebf9e659e590a27b2c42601d0b65c3b>`(double value);
    };
.. _details-class_test_doxyrest:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

This is a testing class for doxyrest.

Methods
-------

.. index:: pair: function; setNewValue
.. _doxid-class_test_doxyrest_1aeebf9e659e590a27b2c42601d0b65c3b:

.. ref-code-block:: cpp
    :class: doxyrest-title-code-block

    void setNewValue(double value)

Sets a custom value.

.. rubric:: Parameters:

.. list-table::
    :widths: 20 80

    *
        - value

        - a new value.

    *
        - std::runtime_error

        - in case the value is invalid.

One can note that the exception is added to the regular parameter list when it should have a separate rubric.

My environment:

$ sw_vers
ProductName:        macOS
ProductVersion:     13.6
BuildVersion:       22G120

$ doxygen --version
1.9.3

$ doxyrest --version
doxyrest v2.1.3 (amd64)

$ sphinx-build --version
sphinx-build 7.2.6

I do appreciate your help since I have a large library with too many "throws" to document.