Adding the whole header content to a Doxygen group

Question

Since it seems such a common task, it is hard for me to believe that if I want to add all the doxygen comments in a header file to a group, that I have to do

foo.h
 /**
 *\addtogroup fooGroup
 * @{
 */
...
...

...
/**@}*/

Is there a way to make this work without the @{ comment?

Answer 1

The short answer is no. An alternative is using the @ingroup command. If you put that command right below the @file command, then the file reference is added to the group, e.g.:

foo.h:
/**
* @file foo.h
* @ingroup fooGroup
*/
...

This also requires that you have defined a group with that name (could be also in a different file):

/**
* @defgroup fooGroup Foo
* @brief    A brief description of the Foo component.
* @details  A more detailed description of the Foo component.
*/

BUT the big disadvantage is that you have to put the @ingroup command for each entity that you want to display in the group documentation. This means you have to add the command to each declaration or definition, like enums, structs, variables and functions.

Using the @addtogroup and the @{ ... @} commands have the big advantage that you don't need to add each entitity to the group using the @ingroup command.

The sense of groups is to collect documentation from different files under one specific name. You could also divide one file into different groups, so the @{ and @} comments are defining the beginning and the end of a region which shall be added to a group name. Another reason is that groups may build hierarchies, e.g. one file with the following code:

/**
 * @addtogroup group_name
 * @{
 */

<Code Example 1>

/** 
 * @} 
 */

/**
 * @addtogroup group_name_2
 * @{
 */

<Code Example 2>

/**
 * @addtogroup sub_group_name
 * @{
 */

<Code Example 3>

/**
 * @addtogroup sub_sub_group_name
 * @{
 */

<Code Example 4>

/** 
 * @} 
 */

/** 
 * @} 
 */

/** 
 * @} 
 */

This would result in the following group hierarchy:

• group_name
• group_name_2
  • sub_group_name
    • sub_sub_group_name

The only thing you might try is to add an Alias for the \addtogroup and { command, like:

ALIAS += "begingroup{1} = \addtogroup \1 \{"

But in this case you would still have to add the @} command at the end of the file.