LibreOffice uses Doxygen comments to generate its API and C++ documentation [1,2]. There are cases where some special Doxygen commands (like @param), that expect a single paragraph of text, are used incorrectly, and several paragraphs appear there without proper enclosing into parblock ... endparblock. [3] E.g., css::sheet::XAreaLinks has such a problem in its aSourceArea documentation [4], where <p> block ends the param, and so the text that was intended to extend the parameter explanation gets out of the block; also, the generated documentation [5] has a second occurrence of "Parameters" section header, inserted after the out-of-parameter text. This easyhack is to fix such places, and put all the paragraphs belonging to a single block, where only one paragraph is expected in the main command. [1] https://api.libreoffice.org/docs/idl/ref/index.html [2] https://api.libreoffice.org/docs/cpp/ref/index.html [3] https://www.doxygen.nl/manual/commands.html#cmdparblock [4] https://opengrok.libreoffice.org/xref/core/offapi/com/sun/star/sheet/XAreaLinks.idl?r=5687eba4#33 [5] https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1sheet_1_1XAreaLinks.html#af482166e53e009514665099dc73c3675
Nam Bui committed a patch related to this issue. It has been pushed to "master": https://git.libreoffice.org/core/commit/6eff24aec6dfb17509af77e12ff9c7f4e0aaf9c7 tdf#158433 Doxygen: multiple paragraphs to parblocks It will be available in 26.2.0. The patch should be included in the daily builds available at https://dev-builds.libreoffice.org/daily/ in the next 24-48 hours. More information about daily builds can be found at: https://wiki.documentfoundation.org/Testing_Daily_Builds Affected users are encouraged to test the fix and report feedback.
Note two things, that became obvious after the first fix landed (thanks Nam Bui!): 1. To search for the problem, the following regex could be useful: @param [^@]*\n\n[^@]*\n 2. After the parblock, there must be no empty line before the next @param: otherwise, the next @param will get a new "Parameters" heading.
I find this command useful for searching for the problem: $ pcregrep -M -r '@param [^@\*]*\n\n[^@\*]*\n' [Insert directory here] '@param [^@]*\n\n[^@]*\n' works but has a false positive where the param block belongs to a void function (no return decorator) and will pick up a <p> in the doc string of the next function.
Nam Bui committed a patch related to this issue. It has been pushed to "master": https://git.libreoffice.org/core/commit/d758550e2d1b4649377b527ad5a1a56c74c07519 tdf#158433 Doxygen: multiple paragraphs to parblocks It will be available in 26.2.0. The patch should be included in the daily builds available at https://dev-builds.libreoffice.org/daily/ in the next 24-48 hours. More information about daily builds can be found at: https://wiki.documentfoundation.org/Testing_Daily_Builds Affected users are encouraged to test the fix and report feedback.