I recently started working on the clang compiler and started to improve
the -Wdocumentation option. I like this option a lot, but unfortunately
it has a lot of false positives. It also seems that the code is longer
actively maintained. My main issue is the detection whether paragraphs
are empty. It has a lot of false positives and also does not recognise
some empty paragraphs. So I have been working on some patches to improve
the empty paragraph detection.
I noticed the parsed comment is stored in the AST and the AST can be
written to XML and HTML files. I wonder whether this output is
considered a part of clang's interface and whether changes to this output
For example following code:
/** @pre @em foo of @ref bar "foo" is @b foobar */
The @ref is now part of a new group 'ReferenceCommandComment' and part
of the paragraph. Also the @b is now recognised again. This new result
looks more like how Doxygen renders the paragraph. The change also fixes
a false positive like:
/** @pre @ref Init is called before using this function. */
Currently the paragraph of @pre is considered empty, after the change it
is no longer considered empty.
The changes to the AST will result in changes in the XML and HTML output.
(I haven't started working on this part yet so no examples.) Is this a
problem? If so what would be the best way forward?