Documentation issues when upgrading to Doxygen 1.9.8

[mudge]

The documentation for this SDK builds fine with Doxygen 1.8.17 (as indicated by the comment in the DoxygenLayout.xml) but has at least two issues when upgrading to the latest version of Doxygen: 1.9.8, released on 25 Aug 2023.

The "API Documentation" tab is missing from the main menu and no modules.html is output

Doxygen 1.8.17	Doxygen 1.9.8

Using the latest default DoxygenLayout.xml produced by Doxygen 1.9.8's doxygen -l restores the contents of the old modules.html but now refers to it as "Topics" instead. Updating our DoxygenLayout.xml restores the previous page (albeit under a new URL):

-    <tab type="modules" visible="yes" title="API Documentation" intro="These are the libraries supplied in the Raspberry Pi Pico SDK"/>
+    <tab type="topics" visible="yes" title="API Documentation" intro="These are the libraries supplied in the Raspberry Pi Pico SDK"/>
+    <tab type="modules" visible="no" title="" intro=""/>

Brief descriptions are no longer extracted for most modules by default

Doxygen 1.8.17	Doxygen 1.9.8

The latter can be fixed by adding JAVADOC_AUTOBRIEF = YES to the Doxyfile to opt into the following functionality:

If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the first line (until the first dot) of a Javadoc-style comment as the brief description. If set to NO, the Javadoc-style will behave just like regular Qt-style comments (thus requiring an explicit @brief command for a brief description.)

Alternatively, we may need to switch to using explicit @brief commands to separate brief descriptions from detailed ones.

[mudge]

As commented in https://github.com/raspberrypi/pico-sdk/pull/1564#issuecomment-1932279064, I'm seeing incorrectly extracted brief descriptions in newer versions of Doxygen (e.g. 1.10.0) even when we're using the explicit \brief command if it isn't separated from the detailed description by a blank line, see https://github.com/raspberrypi/pico-sdk/blob/6a7db34ff63345a7badec79ebea3aaef1712f374/src/rp2_common/hardware_spi/include/hardware/spi.h#L100-L103

[mudge]

In the short term, maybe it's worth defining what version of Doxygen is supported and we advise using that. I believe the latest version that behaves the way we expect is 1.8.17 (before the changes to brief description extraction)?

[aallan]

See #1660.

[krzysztofjozwiak]

Hi, Is lack of backward compatibility in doxygenlayout .xml file expected? I have updated doxygen locally but I cannot update doxygen in our CI currently and ended up with errors from older doxygen version in CI. Also if there are breaking changes introduced IMO it requires changing format version and providing meaningful error if version is not supported/compatible: both versions are using layout 1.0

[aallan]

It's not so much a lack of backwards compatibility in the XML layout, as in the parser. Layout that parsed just fine with older versions of the library don't parse correctly with newer versions which seem to be a lot stricter in what it regards as valid markup.