Как включить несколько абзацев в раздел "Примечания" с помощью Doxygen?

я, наконец, отказываюсь от налога на угловую скобку, наложенного на меня форматом XML-документации Microsoft (и в чем смысл, так как среда MSVC еще не делает ничего необычного с ним для проектов C++) и переключение моего текущего проекта на использование Doxygen с синтаксисом стиля Javadoc.

это фантастика. Встроенная документация намного проще для чтения и ввода, а сгенерированный вывод намного более полезен и универсален. В частности, у меня the MULTILINE_CPP_IS_BRIEF опция включена, что позволяет мне писать столько "краткого" описания, сколько я хочу, а затем разбить мою "подробную" документацию на абзацы, используя пустые строки. Другими словами:

/// Changes the active viewing area of the currently selected region.
///
/// The modification is merely enqueued. This function has no effect until the
/// FlushRegion() function is called.
///
/// Newly-exposed regions will not be repainted automatically. The user must also
/// call the UpdateRegion() function on these regions to cause their contents to
/// be redrawn.
///
/// @param dx The amount, in pixels, to shift the visible region horizontally.
/// @param dy The amount, in pixels, to shift the visible region vertically.
///
/// @remarks
///    Note that this function is reentrant, but not thread-safe!
void ScrollRegion(int dx, int dy);

это дает мне именно тот результат, который я желаю, сохраняя при этом количество шумных мета-команд, таких как @brief и details что я должен использовать.

проблема возникает, когда я пытаюсь включить второй абзац в раздел " замечания, так же, как я сделал (неявно) для раздела "детали". например:

/// Changes the active viewing area of the currently selected region.
///
/// The modification is merely enqueued. This function has no effect until the
/// FlushRegion() function is called.
///
/// Newly-exposed regions will not be repainted automatically. The user must also
/// call the UpdateRegion() function on these regions to cause their contents to
/// be redrawn.
///
/// @param dx The amount, in pixels, to shift the visible region horizontally.
/// @param dy The amount, in pixels, to shift the visible region vertically.
///
/// @remarks
///     Note that this function is reentrant, but not thread-safe!
///
///     If thread safety is required, the user must handle locking and unlocking
///     the region manually.
void ScrollRegion(int dx, int dy);

сгенерированный вывод не интерпретирует второй абзац в @remarks раздел как часть замечаний. я могу сказать, потому что он не отступает на тот же уровень в выводе HTML, и он не находится под <simplesect kind="remark"> тег в выводе XML.

я пробовал добавлять a @par команда до начала второго абзаца, но это я тоже не делал того, что хотел. Новый пункт по-прежнему не является детищем раздела "замечания". В выводе XML он помещается внутри нового <simplesect kind="para"> тег, который является братом оригинального <simplesect kind="remark"> tag.

исследуя это, я увидел, что кто-то другой дублировал :

/// Changes the active viewing area of the currently selected region.
///
/// The modification is merely enqueued. This function has no effect until the
/// FlushRegion() function is called.
///
/// Newly-exposed regions will not be repainted automatically. The user must also
/// call the UpdateRegion() function on these regions to cause their contents to
/// be redrawn.
///
/// @param dx The amount, in pixels, to shift the visible region horizontally.
/// @param dy The amount, in pixels, to shift the visible region vertically.
///
/// @remarks
///     Note that this function is reentrant, but not thread-safe!
/// @remarks
///     If thread safety is required, the user must handle locking and unlocking
///     the region manually.
void ScrollRegion(int dx, int dy);

это тут произведите выход который я желаю. Оба абзаца вложены в <para> теги в <simplesect kind="remark"> тег в выводе XML, и визуальное отношение правильно в выводе HTML. Но это некрасиво и кажется мне ошибкой.

есть ли стандартный способ сделать это, что я упускаю? конечно, я не первый человек, который хочет несколько абзацев в разделе "замечания" моей документации... И это не ограничивается @remarks; то же самое происходит и с @internal, например.

у меня установлена последняя версия Doxygen (1.8.2), но я очень сильно сомневаюсь, что это конкретная версия.