Как сгруппировать несколько замечаний в один абзац?

Question

Я относительно новичок в doxygen, предпочитая Javadocs (когда я писал больше Java) и обычные инструменты обработки текстов (когда я работал в IBM).

Мой стиль комментариев состоит в том, чтобы включить много запущенного повествования, перемежающегося по всей базе кода, так что цель кода очень ясна. Я бы предпочел переработать этот текст, чтобы его можно было использовать для внешней документации для API, которые я создаю.

Когда я использую теги \ примечания, я завершаю каждое примечание \ в виде отдельного абзаца на выходе HTML. Это не выглядит так, как я хочу, чтобы он выглядел. Я не хочу иметь одно гигантское \ примечание, которое может охватывать 6 или 8 блоков кода.

Мой вопрос в том, как заставить doxygen «объединить» несколько разделов \ замечания в один абзац, начиная новый абзац, только когда захочу?

Answer 1

Я не уверен, если я полностью понял вопрос, но если вопрос был: «как использовать более 1 пункт внутри одного замечания тега, вы можете использовать parblock и endparblock команд:

/** 
* \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 
*/ 

Вот вывод HTML:.. вы всегда можете проверить parblock документацию по следующей ссылке parblock doxygen documentation Если вы все еще неудовлетворенный с выходом HTML, я бы порекомендовал вам добавить файл пользовательского CSS с указанием правил замечаний. Вы можете добавить дополнительные файлы CSS через HTML_EXTRA_STYLESHEET: есть класс CSS с названием «примечание раздела», которое должно позволить вам настроить внешний вид; подробнее об этом here. Надеюсь, я тебе помог.