doxygen: @ingroup does not support braces

[Enoch247]

Description

This issue was first noticed here: #20531 (comment)

The Issue

The real problem

Many of the cpu/stm32 specific headers (and probably other CPUs and board specific headers as well) use the following pattern:

/**
 * @ingroup parent_group_name
 * @{
 *
 * @file
 * ...
 */

/* macros, and declaration here. */

/** @} */

This was probably motivated by the very similar pattern used in (for example) many device driver header files with a very small difference:

/**
 * @defgroup group_name
 * @ingroup parent_group_name
 * @{
 *
 * @file
 * ...
 */

/* macros, and declaration here. */

/** @} */

The difference is the presence of the defgroup in the second example. With the defgroup, all the code between the braces is being added to the new group and the new group is added to the parent. This is because the braces are part of the syntax of the defgroup cmd. ingroup syntax does not support use of braces. So when the open brace is encounter by doxygen, it creates what is called a member group, which is not the same as topic groups created by the defgroup command. ingroup cannot be applied to member groups. The ingroup is applied to anything in the same comment block that the cmd is located in. In practice this means that the ingroup is applied to the file cmd within the comment block, but nothing else within the file, as the braces would tend to mislead one to belive. Furthermore, member groups cannot be nested. So files making use of member groups, wind up with nested member groups, because their member groups are nested inside of the accidentally created file-wide member group.

Originally perceived problem

The following is kept as mater of record. It describes what I thought was the root cause. Further testing showed the reall issue as described above.

Doxygen does not allow for member groups to be nested. It is a common idiom that we wrap whole files in a member group so that the cmd @ingroup can be applied to everything in the file. This creates problems when member groups are then actually used in the file. Current behavior of Doxygen seems to be that instead of maintaining a stack to know which group it should place doc elements into, it simply treats the group opening cmd as an indication to set the current group and the closing cmd to exit all groups (ie exit back to top-level/no group).

Note that I am talking about so called member groups. Doxygen does allow topics may be nested under multiple other topics. Confusingly, topics are managed with cmds like @defgroup, @ingroup, etc. but are "topic" groups, not the "member" groups which may not be nested.

The previous paragraphs are kept as mater of record. See real issue above

Steps to reproduce the issue

Go to the doc page for the topic CPU/STM32 (retrieved April 3, 2024) and see that only files and other topics ("Modules") are linked at the bottom. Notice in the STM32 specific SPI header, the file is wrapped (lines 12 - 139) with a group preceded by the @ingroup cpu_stm32 cmd. Also notice that there are several other groups nested in the file's outer most.

Expected results

All the enums, macros, typedefs, etc should be listed in the STM32's main topic page if the outer most group was being honored.

Actual results

Anything after the first opening cmd of a nested member group is not actual added to the outer most group's topic.

Versions

• current master
• 2024.04
• probably affects many more versions

[kfessel]

are you sure that's what is happening?

i think there is a difference between group ( @ingroup @defgroup @weakgroup @addtogroup ) that we are using for files

and membergroups @name

we can have a member group inside a group

but opening a member group cancels automatic membergroups

[kfessel]

@{ and @} are blocks these can be nested but they don't do much if they a not with other commands by the doxgen example they apply they documentation text to all elements inside.

[Enoch247]

I just added steps to reproduce. I think it should prove that our use of nesting is breaking things. This isn't the best example in that we probably actually are okay with the outputted doc in this case, but it is the example I have in-front of me and understand best at this time.

[Enoch247]

Another ancillary thing I noticed is that there seems to be alot of misunderstanding surrounding use of the member groups exacerbated by copy-pasting. I'm not actually sure that the member group used here does anything. The purpose of member groups is to group multiple doc blocks together, but the group is opened and closed in the same block. So nothing is actually grouped.

[Enoch247]

I believe the @addtogroup supports use of the opening and closing braces, but @ingroup does not, maybe we could replace our use of ingroup with addgroup?

[kfessel]

you are probably rigth, in that there is missing understanding of these blocks, groups and member-group things and a lot of copy and paste.

[Enoch247]

you are probably rigth, in that there is missing understanding of these blocks, groups and member-group things and a lot of copy and paste.

I know I am guilty of it.

[Enoch247]

I believe

/**
 * @ingroup foo
 * @{
*/

/** @} */

creates a member group (between the braces) and places that member group into the topic group foo. Where-as:

/**
 * @addtogroup foo
 * @{
*/

/** @} */

adds everything between the braces to the group foo.

[kfessel]

I believe the @addtogroup supports use of the opening and closing braces, but @ingroup does not, maybe we could replace our use of ingroup with addgroup?

@addgroup id title adds the things it is documenting to an allready existing group if exiting else it creates that group giving it the title
@ingroup id only adds to an existing group
@defgroup id title creates a new group can't be done twice (overwites addgroup titles)

all of them can have blockes open

[kfessel]

/**
 * @ingroup foo
 * @{
*/

/** @} */

creates a member group (between the braces) and places that member group into the topic group foo. Where-as:

no this puts things in a group that must be existing (created by either: defgroup or addgroup or weakgroup)

/**
 * @addtogroup foo
 * @{
*/

/** @} */

adds everything between the braces to the group foo.

either add to an existing group or creates a new one

[Enoch247]

I believe the @addtogroup supports use of the opening and closing braces, but @ingroup does not, maybe we could replace our use of ingroup with addgroup?

@addgroup id title adds the things it is documenting to an allready existing group if exiting else it creates that group giving it the title @ingroup id only adds to an existing group @defgroup id title creates a new group can't be done twice (overwites addgroup titles)

all of them can have blockes open

I agree with everything above, except the statement that @ingroup supports braces. I think we are unwitting creating a member group and then adding the member group to the topic group. I can't find anything to support the statment that ingroup supports brace syntax.

addtogroup on the other hand show using braces in the example right in the doc for the cmd.

[Enoch247]

hmm. I may be wrong

To avoid putting \ingroup commands in the documentation for each member you can also group members together by the open marker @{ before the group and the closing marker @} after the group. The markers can be put in the documentation of the group definition or in a separate documentation block.

(https://www.doxygen.nl/manual/grouping.html)

But still something is up. You can see it int the example I provide for the steps to reproduce.

[kfessel]

at least we wouldn't be alone with that

https://github.com/zephyrproject-rtos/zephyr/blob/bba8641354bfbf83743c032c378a791b941ad7fc/include/zephyr/ipc/icmsg.h#L23-27

[kfessel]

in the

hmm. I may be wrong

To avoid putting \ingroup commands in the documentation for each member you can also group members together by the open marker @{ before the group and the closing marker @} after the group. The markers can be put in the documentation of the group definition or in a separate documentation block.

(https://www.doxygen.nl/manual/grouping.html)

But still something is up. You can see it int the example I provide for the steps to reproduce.

in the spi file are some #ifndef DOXYGEN those might mixup things

[kfessel]

doxygen also reads some blocking/grouping from the comments and some from the source code

[Enoch247]

I too was suspicious of the #ifndef DOXYGEN statement, but couldn't find an explanation of why they could be the root cause. I am going to experiment a bit more and see if I can't get some more facts to work from.

[Enoch247]

Ok, so I tried removing all the inner member groups, still none of the comment blocks showed up in the parent topic.

Next, I replaced ingroup with addtogroup, and everything showed up in the parent topic.

Next, I put all the inner member groups back, leaving the addtogroup in-palce, and everything continued to show in the parent.

Finally, I restored the file back to its original state and added a defgroup right before the ingroup. git diff shows:

diff --git a/cpu/stm32/include/periph/cpu_spi.h b/cpu/stm32/include/periph/cpu_spi.h
index 3fa42e11d4..26a49975a4 100644
--- a/cpu/stm32/include/periph/cpu_spi.h
+++ b/cpu/stm32/include/periph/cpu_spi.h
@@ -8,6 +8,7 @@
  */
 
 /**
+ * @defgroup        cpu_stm32_periph_spi SPI
  * @ingroup         cpu_stm32
  * @{
  *

And now the parent topic (CPU/STM32) contains the new SPI topic with everything in the file showing under the new topic group.

Conclusion, ingroup does not support braces, but defgroup and addtogroup do. ingroup works the way we use it in many places, because we are using it to add a newly defined group to a parent.

[Enoch247]

I now re-read the previous quote:

To avoid putting \ingroup commands in the documentation for each member you can also group members together by the open marker @{ before the group and the closing marker @} after the group. The markers can be put in the documentation of the group definition or in a separate documentation block.

(https://www.doxygen.nl/manual/grouping.html)

and see that the use of braces is referred to "put in the documentation of the group definition" (defgroup), "or in a separate documentation block" (not really sure what they mean here but they don't really tie it back to ingroup either). I think this is just a poor choice of words here and what they are trying to say is that you can use braces (with other commands) if you don't want to plaster every comment block with an ingroup cmd.

[kfessel]

I think to understand the choice of command words and their why you would need to dig through the history of doxygen and maybe javadoc.

Thanks for investigating

[Enoch247]

I have updated this issue's title and description to describe the real problem that is occurring.

A very simple approach to fixing this is replacing ingroup with addtogroup wherever ingroup is used without a defgroup. This approach would not add any new document groups and honor (I believe) what the original authors intended in their doxgen blocks. However, I believe heavy use of addtogroup could lead to maintainability problems.

The other approach is to add a defgroup everywhere their is in ingroup without a defgroup. This approach would add new topic groups to the doc.

A third approach, and I believe is the best, is remove these braces when defgroup is not present. This will keep the documentation output the same, leaving the file being added to the topic group. The files contents will not be added to the topic group. But the contents will still be visible when you go the the file's documentation page.

[kfessel]

thank you for diving

A very simple approach to fixing this is replacing ingroup with addtogroup wherever ingroup

addtogroup would need a group title i think -not sure it seems to be optional- and the first addtogroup with title would define the group title

I would like to make @miri64 (does a lot of documentation things) and @maribu (most recent edits in the /doc folder) aware of this issue.

@Enoch247 may be a/some PR(s) would having one or some file(s) changed in the suggested ways would help to illustrate (please link this issue)

I think there also was some thought in the air of having another renderer (MkDocs or Sphinx ) for the documentation output. We certainly will want to avoid compatibility issues

[maribu]

Regarding the use of Sphinx: We would use breathe, which parses the XML output of Doxygen, to generate the API doc. Thus, switching to breathe would only fix the "website looks ugly" issue. Any issues with Doxygen would stay by thay switch.

[Enoch247]

Time permitting (I am very deep into working on the STM32H7 port at the moment, which has lead down some other tangential paths) I can do a example PR as suggested.

addtogroup would need a group title i think -not sure it seems to be optional- and the first addtogroup with title would define the group title

Not in this case. In the cases I describe, it is only to replace ingroup. So addtogroup would be used to add items to already existing groups. Those existing groups are already defined with defgroup elsewhere, which is where the title is set.