Subgroups with the same name in different groups

I just started using Doxygen for the first time and ran into the following problem: I’m trying to create multiple subgroups with the same name like this:

- Group 1
    - Constructors
    - Other
- Group 2
    - Constructors
    - Other

Instead what I get is this:

- Group 1
    - Constructors
        - (Constructors both from Group 1 and 2)
    - Other
        - (Others from both Group 1 and 2)
- Group 2
    - Constructors
        - (Constructors both from Group 1 and 2)
    - Other
        - (Others from both Group 1 and 2)

My current code looks like this (in separate .h files)

/** @defgroup Group1
* Description for Group 1
*/
/** @defgroup Group2
* Description for Group 2
*/
/* @defgroup Constructors
* @ingroup Group1
*/
/* @defgroup Constructors
* @ingroup Group2
*/
/* @defgroup Other
* @ingroup Group1
*/
/* @defgroup Other
* @ingroup Group2
*/

/**
* @ingroup Group1
* @{
*/
 class Class1 {
     /**
     * @ingroup Constructors
     * @{
     */
     Class1();
     (other constructors)
     /** @}*/
     /**
     * @ingroup Other
     * @{
     */
      void Random();
      (other functions)
     /** @}*/
 }; /** @}*/
/**
* @ingroup Group2
* @{
*/
 class Class2 {
     /**
     * @ingroup Constructors
     * @{
     */
     Class1();
     (other constructors)
     /** @}*/
     /**
     * @ingroup Other
     * @{
     */
      void Random();
      (other functions)
     /** @}*/
 }; /** @}*/

I tried to keep the code short, but I hope my question is still clear. Thanks in advance!

Answer

Short answer:

  • Make sure to declare groups in doxygen commments (/**), not just C comments
  • group definition takes a name and a title. The name (Constructors_1) must be globally unique, and acts as an identifier. The title (Constructors) is what is rendered, and does not need to be unique.
  • Nesting groups can be used to manually organize some doc. Doing that on C++ methods of a class, however, is counter productive, as it will confuse doxygen (see how group 1 and 2 are broken in the example below), which naturally documents methods of a class with the class, not elsewhere.
  • use groups to organize entire classes (with all the content) or functions into several sub groups, but do not try to break down classes into smaller parts.

Long answer:

/** @file foo.cc
  Doxygen example.
*/

/** @defgroup Group1
* Description for Group 1
*/
/** @defgroup Group2
* Description for Group 2
*/
/** @defgroup Constructors_1 Constructors
  Constructors from group 1.
* @ingroup Group1
*/
/** @defgroup Constructors_2 Constructors
  Constructors from group 2.
* @ingroup Group2
*/
/** @defgroup Other_1 Other
  Misc from group 1.
* @ingroup Group1
*/
/** @defgroup Other_2 Other
  Misc from group 2.
* @ingroup Group2
*/

/** @defgroup Group3
* Description for Group 3
*/
/** @defgroup Stuff_3 Stuff
  Stuff.
* @ingroup Group3
*/
/** @defgroup More_stuff_3 More stuff
  More stuff.
* @ingroup Group3
*/

/**
* @ingroup Group1
* @{
*/
 class Class1 {
     /**
     * @ingroup Constructors_1
     * @{
     */
     /** This is Class1. */
     Class1();
     /** @}*/

     /**
     * @ingroup Other_1
     * @{
     */
     /** This is Random 1. */
      void Random();
     /** @}*/
 };
/** @}*/

/**
* @ingroup Group2
* @{
*/
 class Class2 {
     /**
     * @ingroup Constructors_2
     * @{
     */
     /** This is Class2. */
     Class2();
     /** @}*/

     /**
     * @ingroup Other_2
     * @{
     */
     /** This is Random 2. */
      void Random();
     /** @}*/
 };
/** @}*/

/**
* @ingroup Group3
* @{
*/

void init_group_3();

     /**
     * @ingroup Stuff_3
     * @{
     */
     /** This is some stuff. */
     void do_something_here();
     /** @}*/

     /**
     * @ingroup More_stuff_3
     * @{
     */
     /** This is more stuff. */
     void do_something_more_here();
     /** @}*/
 };
/** @}*/

Tested with Doxygen 1.9.2, group 3 works as expected, group 1 and 2 do not render the content properly, because of manually assignment of methods of a class to another group.