Use of sections within a module group in doxygen

Question

I seek the preferred way to structure the contents of a doxygen module group. For example I want to structure the @details text in the following module group in different sections. Especially each of the sections should appear in the bookmarks of the generated PDF (as child elements of the module group):

@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.
@}

A way could be using @section @subsection etc, but the doxygen manual says:

Warning: This command only works inside related page documentation and not in other documentation blocks!

Is it possible to use @section or are there other (better) ways to do this?

Edit: The behavior using @section seems indeed odd, for example I tried something like this:

@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.

@}

The result looks fine and has in this case the following structure in the PDF:

4.1 lorem
4.1.1 Lorem ipsum
4.1.2 Pellentesque
4.1.3 Integer sapien est

Now if a add @file a @details section containing no text appears in the output I can't get rid of. It looks like this (I also tested adding another group containing a @file - same result):

4.1 lorem
4.1.1 Detailed Description
4.1.2 Lorem ipsum
4.1.3 Pellentesque
4.1.4 Integer sapien est

Then I tried to move the sections and make them subsections of the "Detailed Description" -which would be logically okay. But when I change them to @subsection 's they completely disappear. Doxygen warns in this case it has found a subsection out of section context so obviously it doesn't realize it generated this mysterious empty @details section.

Next idea was to use the Markdown support to do it. In this case sections aren't put into the PDF bookmarks so it looks okay - but in latex code they are still on same level as the @details section. And subsections in Markdown disappear as well. I've no idea what is going on, but I can't be the first person trying to structure things in a module group.

aldr aldr · Accepted Answer · 2013-06-26T13:39:38

I tried your example myself and if you put the @file between your @{ ... @} like this,

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

then the standard Doxygen Layout is created.

If you move the @file outside, then your like this, then it should work.

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

However, if you really need the @file within your @defgroup lorem @{ ... @}, there are two ways to achive it.

FIRST:

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

SECOND:

Change the standard doxygen layout.

To do this, follow the manuals description here, beginning at: Changing the layout of pages, by creating your custom DoxygenLayout.xml.

Now, edit the DoxygenLayout.xml and search for the <group> tag.

There will find <detaileddescription title=""/> tag, change it to <detaileddescription visible="no" title=""/>and the `Detailed Description" bugging you should vanish.

Use of sections within a module group in doxygen

2 Answers