Использование разделов в группе модулей в doxygen

Question

Я ищу предпочтительный способ структурирования содержимого группы модулей doxygen. Например, я хочу структурировать текст @details в следующей группе модулей в разных разделах. Особенно каждый из разделов должен появиться в закладках сгенерированного PDF (в качестве дочерних элементов группы модулей):

@defgroup lorem 
@{ 
    @brief 

    Lorem ipsum 

    @details 

    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut purus elit, vestibulum 
    ut, placerat ac, adipiscing vitae, felis. Curabitur dictum gravida mauris. Nam arcu 
    libero, nonummy eget, consectetuer id, vulputate a, magna. Donec vehicula augue eu 
    neque. 

    Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis 
    egestas. Mauris ut leo. Cras viverra metus rhoncus sem. Nulla et lectus vestibulum 
    urna fringilla ultrices. Phasellus eu tellus sit amet tortor gravida placerat. 

    Integer sapien est, iaculis in, pretium quis, viverra ac, nunc. 
    Praesent eget sem vel leo ultrices bibendum. Aenean faucibus. Morbi dolor nulla, 
    malesuada eu, pulvinar at, mollis ac, nulla. Curabitur auctor semper nulla. 
    Donec varius orci eget risus. Duis nibh mi, congue eu, accumsan eleifend, 
    sagittis quis, diam. Duis eget orci sit amet orci dignissim rutrum. 
@} 

Способ может быть с помощью @section @subsection и т.д., но руководство Doxygen говорит:

Предупреждение: Эта команда работает только в связанной документации страниц , а не в других блоках документации!

Можно ли использовать @секцию или есть другие (лучшие) способы сделать это?

---

Edit: поведение с помощью @section кажется действительно странным, например, я пытался что-то вроде этого:

@defgroup lorem 
@{ 

@brief 

Lorem ipsum 

@section sec0 Lorem ipsum 

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut purus elit, vestibulum 
ut, placerat ac, adipiscing vitae, felis. Curabitur dictum gravida mauris. Nam arcu 
libero, nonummy eget, consectetuer id, vulputate a, magna. Donec vehicula augue eu 
neque. 

@section sec1 Pellentesque 

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis 
egestas. Mauris ut leo. Cras viverra metus rhoncus sem. Nulla et lectus vestibulum 
urna fringilla ultrices. Phasellus eu tellus sit amet tortor gravida placerat. 


@section sec2 Integer sapien est 

Integer sapien est, iaculis in, pretium quis, viverra ac, nunc. 
Praesent eget sem vel leo ultrices bibendum. Aenean faucibus. Morbi dolor nulla, 
malesuada eu, pulvinar at, mollis ac, nulla. Curabitur auctor semper nulla. 
Donec varius orci eget risus. 
Duis nibh mi, congue eu, accumsan eleifend, 
sagittis quis, diam. Duis eget orci sit amet orci dignissim rutrum. 

@} 

Результат выглядит хорошо, и в этом случае имеет следующую структуру в формате PDF :

• 4,1 Lorem
• 4.1.1 Lorem Ipsum
• 4.1.2 Pellentesque
• 4.1.3 Integer Sapien Эст

Теперь, если добавить @file раздел @details, не содержащего текст появляется на выходе я не могу избавиться. Похоже, что это (я также протестировали добавив еще одну группу, содержащую @file - тот же результат):

• 4,1 Lorem
• 4.1.1 Подробное описание
• 4.1.2 Lorem Ipsum
• 4.1.3 Pellentesque
• 4.1.4 Integer Sapien Эст

Затем я попытался переместить разделы и сделать их подразделов «Подробное описание» -Какой бы logicall хорошо. Но когда я меняю их на @subsection, они полностью исчезают. Doxygen предупреждает, что в этом случае он нашел раздел вне контекста раздела, поэтому, очевидно, он не понимает, что он создал этот таинственный пустой раздел @details.

Следующая идея состояла в том, чтобы использовать поддержку Markdown для этого. В этом случае разделы не помещаются в закладки PDF, поэтому все выглядит нормально - но в латексном коде они все еще находятся на том же уровне, что и раздел @details. И подразделы в Markdown также исчезают. Я понятия не имею, что происходит, но я не могу быть первым, кто пытается структурировать вещи в группе модулей.

Answer 1

Я попробовал ваш пример себя, и если вы поставите @file между вашим @{ ... @}, как это,

/**
@defgroup lorem
@{
...
@file
@}
*/

затем создается стандартный макет Doxygen.

Если вы перемещаете @file снаружи, то ваш подобный этому, тогда он должен работать.

/**
@defgroup lorem
@{
...
@}
@file
*/

Однако, если вам действительно нужно @file в вашем @defgroup lorem @{ ... @}, есть два способа для того чтобы достигнуть его.

ПЕРВЫЙ:

/**
@defgroup file
@{
@file
@defgroup lorem
@{
...
@}
@}
*/

ВТОРОЙ:

Изменение стандартной раскладке Doxygen.

Для этого следуйте инструкциям по эксплуатации here, начиная с: Изменение макета страниц, путем создания пользовательского DoxygenLayout.xml.

Теперь отредактируйте DoxygenLayout.xml и найдите тег <group>.

Там будет найти <detaileddescription title=""/> тег, измените его на <detaileddescription visible="no" title=""/> и `Подробное описание» подслушивание вы должны исчезнуть.

Answer 2

Если вы просто хотите, чтобы структурировать разделы в описании группы, то я бы просто использовать HTML и вставить <h1>Section name here<\h1> и т.д.

В качестве альтернативы Markdown ## раздел маркировки может работать.

Я не знаю, насколько хорошо они проникают в LaTex и PDF, поскольку я никогда не использовал этот выходной маршрут. Тем не менее, я уверен, что использование HTML даст более надежные результаты, чем использование @section, которое, как предупреждает руководство, просто не предназначено для использования здесь, а вместо этого является частью иерархии @page/@section/@subsection для массовой прозы. Эти наборы команд плохо смешиваются в Doxygen.

Расположение @file в экзотических положениях (согласно предложению альдера) подвержено очень странным результатам. Это просто блок описания для физического файла и лучше всего используется именно так.