Doxygen retval comment output different in 4.28 and 4.29

[Geddih]

Hi, I'm using Breathe to generate user documentation for an embedded C application.
Sphinx=3.5.4, Python=3.9.4, Doxygen=1.9.1, TexLive 2021.

I've noted that Breathe outputs the following retval Doxygen comments differently in 4.28 and 4.29

* @retval "Discovery status" - The discovery status of the \c discovery_context. See the discovery status
*                              enum for more information on what each code means.
* @retval MAX_EVENTS         - The pointer to the discovery service context \c discovery_context is NULL,
*                              or the discovery service has entered the invalid \c MAX_EVENTS state, which
*                              should never occur unless manually set.

The exported Doxygen XML is:

<parameterlist kind="retval"><parameteritem>
<parameternamelist>
<parametername>Discovery status</parametername>
</parameternamelist>
<parameterdescription>
<para>- The discovery status of the <computeroutput>discovery_context</computeroutput>. See the discovery status enum for more information on what each code means. </para></parameterdescription>
</parameteritem>
<parameteritem>
<parameternamelist>
<parametername>MAX_EVENTS</parametername>
</parameternamelist>
<parameterdescription>
<para>- The pointer to the discovery service context <computeroutput>discovery_context</computeroutput> is NULL, or the discovery service has entered the invalid <computeroutput>MAX_EVENTS</computeroutput> state, which should never occur unless manually set. </para></parameterdescription>
</parameteritem>
</parameterlist>

The PDF outputs are:

Breathe 4.28 (which looks correct to me)

Return Value
    • Discovery status: - The discovery status of the discovery_context. See the discovery status enum for more information on what each code means.
    • MAX_EVENTS: - The pointer to the discovery service context discovery_context is NULL,or the discovery service has entered the invalid MAX_EVENTS state, which should never occur unless manually set.

Breathe 4.29

Returns Discovery statusDiscovery status - The discovery status of the discovery_context. See the discovery status enum for more information on what each code means.

Returns MAX_EVENTSMAX_EVENTS - The pointer to the discovery service context discovery_context is NULL, or the discovery service has entered the invalid `MAX_EVENTS` state, which should never occur unless manually set.

I also tried 4.29.1 which gives the same output as 4.29.

[vermeeren]

@Geddih There were some rendering changes with #670, so the layout changing is more or less expected.

What is of course not expected is the duplicate with Discovery status and MAX_EVENTS. Could you also test with HTML output? Because it did not duplicate with Breathe docs I am thinking it might be PDF output specific. That'll help to determine where to look.

[Geddih]

Hi, @vermeeren, thanks for looking at this, the HTML output shows similar issues.

Breathe 4.28

Breathe 4.29

[jakobandersen]

Do you have example for reproduction?

[Geddih]

I'll put a cut down example together and verify the issue myself. I can't share the full source.

[Geddih]

@jakobandersen attached ZIP contains XML (Doxygen 1.18.3) for a function and a cutdown version of my project.

documentation.zip

[Geddih]

Thanks for fixing the duplicate retval value in 4.30. However, I'm still getting a different layout for return values compared to parameters - see attached. Parameters use a bulleted list in 4.28 and 4.30; returns use a bulleted list in 4.28 but a description list in 4.30.

[jakobandersen]

The difference between parameters and returns is most like in how Sphinx handles them: the parameters fields are groupable, so if a directive has more than one it will collect them and make a list. The return field doesn't have this, and I'm unsure if it is easy to change it due to the rtype field that interacts with it.
Perhaps we should do this grouping manually in Breathe to get something similar to how autodoc for Python does it (see first screen shot at sphinx-doc/sphinx#9119).