Bug 158433 - Doxygen: put multiple paragraphs into parblocks where necessary
Summary: Doxygen: put multiple paragraphs into parblocks where necessary
Status: NEW
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: sdk (show other bugs)
Version:
(earliest affected)
unspecified
Hardware: All All
: medium enhancement
Assignee: Not Assigned
URL:
Whiteboard:
Keywords: difficultyBeginner, easyHack, topicCleanup
Depends on:
Blocks:
 
Reported: 2023-11-29 07:44 UTC by Mike Kaganski
Modified: 2023-11-29 08:06 UTC (History)
1 user (show)

See Also:
Crash report or crash signature:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Mike Kaganski 2023-11-29 07:44:53 UTC
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