Subgroups with the same name in different groups

Question

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!

I don't know doxygen but should `@ingroup Group 1` be `@ingroup Group1`? — Alan Birtles, Sep 16 '21 at 10:00
You're right I was missing the @defgroup for the subgroups thanks :) — Dóri, Sep 16 '21 at 10:06
I'm not really sure what you mean by that? Could you give an example? — Dóri, Sep 16 '21 at 10:45
I think @Dóri is rifght the syntax of `\defgroup` is `\defgroup (group title)` some use different `` otherwise please give a complete example. Which version of doxygen? — albert, Sep 16 '21 at 12:06
I added the full version (or, well, as far as examples go). The Doxygen version is 1.9.2. — Dóri, Sep 16 '21 at 12:18
Shouldn't there be a semi-colon (`;`) after the closing bracket of the class? and on other places? I assume you use c++. Be sure that the code is valid code! — albert, Sep 16 '21 at 12:25
Yeah you're right. Like I said it's just an example not the actual code so I didn't pay much attention to that — Dóri, Sep 16 '21 at 12:28
Even an example should be correct otherwise we are in the dark... Show also the output of `doxygen -x Doxyfile` (for the example) — albert, Sep 16 '21 at 12:31
If you mean the doxygen log I uploaded it here: https://tmpfiles.org/dl/114973/doxygen_log.txt — Dóri, Sep 16 '21 at 12:51
I'm sorry I really don't know what other settings file there is. — Dóri, Sep 16 '21 at 13:06
This is not a settings file but running doxygen directly on the settings file so it gives the differences between the default settings and the settings you used. In the doxywizard this is the output given in the "run"-tab and using the "condensed" "show configuration" — albert, Sep 16 '21 at 13:09
I tried running it in the folder where the Doxyfile is, if that's what you meant. It just gave me an empty webpage. Then again, the only settings I changed was to not create a latex file. — Dóri, Sep 16 '21 at 13:18
The output of `doxygen -x` is displayed in the terminal from where you run doxygen and it only checks the settings file, so it doesn't create any HTML file, but from the description you gave it looks like you only changed `GENERATE_LATEX` to `NO`. Best is to run your example (after corrections so it is valid code) and post the image / screenshot of the relevant result, indicating the problem, in your original question — albert, Sep 16 '21 at 13:22
Here's screenshot of my actual project (custom math library): https://i.gyazo.com/9fdead70f18b90210ffa15a6a2dbd735.png You can see that depsite being in the Mat3x3->Constructors menu, it lists the constructors of the vector, quaternion and transform as well. This is the same in every subgroup seen on the left. — Dóri, Sep 16 '21 at 13:33
post the image / screenshot of the relevant result, indicating the problem, in your original question. urthermore I cannot relate the image in any way to your question / problem. — albert, Sep 16 '21 at 14:02

Marc Alff · Accepted Answer · 2021-09-27T14:59:52.647

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.

Thanks for the answer but I ended up just writing my own documentation tool. Finished in about 3 days — Dóri, Sep 27 '21 at 15:21

Subgroups with the same name in different groups

1 Answers1