The reason for the behavior observed by @mguetschow lies in the priority of the grouping commands: https://www.doxygen.nl/manual/grouping.html

The priorities of grouping definitions are (from highest to lowest): \ingroup, \defgroup, \addtogroup, \weakgroup.

The @ingroup command has a higher priority than @defgroup, which means that the contents of the header are not added to the group defined by @defgroup in the mutex.doc.md file. However the contents of the Markdown file can't be added to the header either, therefore Doxygen only creates the separate documentation page for the header.

The opening brackets should be below the command as well, but that is not the cause of the issue.

Great, that did the trick: https://ci.riot-os.org/results/26628cecaa754671bd7631723421d236/doc-preview/group__core__sync__mutex.html

It should not show a different behavior

defgroup ^= create a new group and put stuff inside
ingroup ^= put stuff in group

defgroup, ingroup ^= create a new group put it inside another group and put stuff into the new (sub)group

addtogroup ^= defgroup but do not care if already existing (basically fallback to ingroup) (defgroup with same label has priority for title and placement of that group)
weakgroup ^= addtogroup but this title has even less priority for the label and placement

The priotity is just within one doc-comment

search for ingroup -> place there; search for defgroup -> create new group and place there.

It should not show a different behavior

It's not entirely unlikely that there's a bug in Doxygen in that regard...

The priotity is just within one doc-comment

..but I didn't find any reference in the Doxygen grouping documentation that this is the case. Or I missed it.

To define a group, you should put the \defgroup command in a special comment block. ...

defgroup ^= create a new group and put stuff inside

You can make an entity a member of a specific group by putting a \ingroup command inside its documentation block.

ingroup ^= put stuff in group

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.

doxygen should have applied the ingroup label to everything in that @{ group but it somehow created a subgroup

If you don't want Doxygen to enforce unique labels, then you can use \addtogroup instead of \defgroup. It can be used exactly like \defgroup, but when the group has been defined already, then it silently merges the existing documentation with the new one.

addtogroup is defgroup with ingroup fallback

since non of this steps does nothing about priorities the priorities thing must be something else which is the evaluation order with in one step of placing a thing in the the documentation it goes ingroup then defgroup then add/weakgroup

so it does not care whether one writes :

@ingroup in
@defgroup def
@addgroup add

or

@defgroup def
@addgroup add
@ingroup in

both will result in in>def>add in the group tree and the documented thing being placed there

maybe there is something in the documentation that says "files implicitly define their own (sub)group unless there is an explicit defgroup (or addtogroup) " and addtogroup being defgroup

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.

doxygen should have applied the ingroup label to everything in that @{ group but it somehow created a subgroup

I think @{ ... @} just starts a new group (without giving it a name) which is then put inside another group with @ingroup. So that's consistent with what we saw.

you can see this not happening in the sys_event documentation (all the different headers are added to the same group using an ingroup statement) and there is also no subgroup with addtogroup

and the thing i cited is from the doxygen documentation

To avoid putting \ingroup commands in the documentation -- as in thevfollowing will have the same effect-- for each member you can also group members together by the open marker @{

you can see this not happening in the sys_event documentation (all the different headers are added to the same group using an ingroup statement) and there is also no subgroup with addtogroup

Ah now I see what you mean, different semantics if @defgroup is followed by @{ vs. some @ingroup is followed by @{ (as in if you split the @defgroup out to a doc.md). But I guess in that case you actually need @addtogroup then. As in @defgroup implies @addtogroup, but @ingroup doesn't.

All the other header files listed on the Event Queue API page have none of their symbols listed on that same page directly, but only on the header file pages, e.g., https://doc.riot-os.org/callback_8h.html. Those implicit header file groups have no name (I would expect this example to be sys_event_callback for example).