How do I group multiple remarks into a single paragraph?

Question

I'm relatively new to doxygen, having preferred Javadocs (when I was writing more Java) and regular word processing tools (when I was working for IBM).

My comment style is to include a lot of running narrative interspersed throughout the code base so that the purpose of the code is very clear. I'd prefer to re-work that text so it can be used to external documentation for the APIs I'm producing.

When I use \\remark tags I wind up with each \\remark as a separate paragraph in the HTML output. That doesn't look the way I want it to look. I don't want to have one giant \\remark which might cover 6 or 8 blocks of code, either.

My question is this -- how can I tell doxygen to "merge" multiple \\remark sections into a single paragraph, starting a new paragraph only when I want it to?

Answer 1

I'm not sure if I fully understood the question, but if the question was: "how to use more than 1 paragraph inside a single remark tag, you can use parblock and endparblock commands:

/**
 *  \file utils.h
 *  \brief TODO complete the documentation of utils.h
 *
 * \remark  Lorem ipsum dolor sit amet, ex everti iracundia laboramus vel, in tota sensibus posidonium eam. His ei expetenda splendide, has eu iusto delicatissimi. Mei dolor deseruisse et. Viris graeco necessitatibus an est, quod reque vulputate sea cu, an has simul nihil numquam. Modo animal assentior pri ut, te mea duis prima, esse sonet ut vim. Duo in duis legere molestie.
 *
 * Ea mel prima atomorum liberavisse, ei odio voluptua dissentiet vix. Vix an ornatus suscipit perfecto. Ut propriae omnesque cum, usu ferri commune tacimates te, erant definitionem vim id. Vix cu copiosae imperdiet. Vis fierent nominati patrioque et, eam menandri vituperatoribus ei, ea has veritus volutpat neglegentur. Ius cu posse novum utroque.
 *
 * Ad per nobis periculis, legere cetero duo ut. In vis nihil admodum suscipit, per alia consequat expetendis ad, ex erant vocibus adversarium mel. Vix ut modus gloriatur, falli vitae eu eam, te per dicat persius. Vis nostrud maiorum et, sea ut etiam perfecto. Cum ut quod legimus convenire, iriure fabellas gloriatur qui ex.
 *
 * \remark
 *
 * \remark \parblock
 *
 * Lorem ipsum dolor sit amet, ex everti iracundia laboramus vel, in tota sensibus posidonium eam. His ei expetenda splendide, has eu iusto delicatissimi. Mei dolor deseruisse et. Viris graeco necessitatibus an est, quod reque vulputate sea cu, an has simul nihil numquam. Modo animal assentior pri ut, te mea duis prima, esse sonet ut vim. Duo in duis legere molestie.
 *
 * Ea mel prima atomorum liberavisse, ei odio voluptua dissentiet vix. Vix an ornatus suscipit perfecto. Ut propriae omnesque cum, usu ferri commune tacimates te, erant definitionem vim id. Vix cu copiosae imperdiet. Vis fierent nominati patrioque et, eam menandri vituperatoribus ei, ea has veritus volutpat neglegentur. Ius cu posse novum utroque.
 *
 * Ad per nobis periculis, legere cetero duo ut. In vis nihil admodum suscipit, per alia consequat expetendis ad, ex erant vocibus adversarium mel. Vix ut modus gloriatur, falli vitae eu eam, te per dicat persius. Vis nostrud maiorum et, sea ut etiam perfecto. Cum ut quod legimus convenire, iriure fabellas gloriatur qui ex.
 *
 * \endparblock
 *
 * \remark
 *  third remark
 */

Here's the HTML output: . You can always check parblock documentation by following the link parblock doxygen documentation . If you are still unsatisfied with the HTML output, I would recommend you to add a custom CSS file specifying remarks rules. You can add additional CSS files via HTML_EXTRA_STYLESHEET: there is CSS class named "section remark" that should allow you to customize the appearance; more info about this one here . I hope I helped you.