Open mudge opened 7 months ago
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
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)?
See #1660.
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
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.
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 outputUsing the latest default
DoxygenLayout.xml
produced by Doxygen 1.9.8'sdoxygen -l
restores the contents of the oldmodules.html
but now refers to it as "Topics" instead. Updating ourDoxygenLayout.xml
restores the previous page (albeit under a new URL):Brief descriptions are no longer extracted for most modules by default
The latter can be fixed by adding
JAVADOC_AUTOBRIEF = YES
to theDoxyfile
to opt into the following functionality:Alternatively, we may need to switch to using explicit
@brief
commands to separate brief descriptions from detailed ones.