Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
ceandrade opened this issue Sep 28, 2023 · 0 comments
Open

Comments

@ceandrade
Copy link

ceandrade commented Sep 28, 2023

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.

@ceandrade ceandrade changed the title Doxyrest is not processing/generating throw statements / exceptions Doxyrest is not processing/generating C++ throw statements / exceptions Sep 28, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant