Monday, 22 November 2010

Subgrouping C code in Doxygen

The Doxygen documentation about grouping concerns itself about C++ code and using the groups with plain C wasn't quite as forward as I thought. I wanted to create a main group (shown as a top-level page) and sub-groups below it in a manner where the files belonging to a sub-group are not shown on the ancestor group pages. E.g. I wanted the structure to be something like
Main
main.c
Module
module.c
helper.c


The files wouldn't obviously been shown on the listing, but they would appear in the Main and Module pages' Files section.

After a bit of hacking, this is how I accomplished it:

main.c:
/** @file main.c
*
* @brief
* (other Doxygen tags)
*
* @ingroup main_group
*/

/** @defgroup main_group
This is the main group of the application.
*/

module.c:
/** @file module.c
* (other tags)
* @ingroup module
*/

/** @defgroup module
* This is the sub group of the application. */
* @ingroup main_group */

helper.c:
/** @file helper.c
* (other tags)
* @ingroup module
*/


So the trick is to define separately the new groups and what group (if any) they belong to. If I tried to have @defgroup inside the file header block, things just didn't seem to work. At the best main.c was not shown under main_group. I think this is because @ingroup only takes into account the previous suitable tag. So if there is a @defgroup before it, @ingroup adds this group to whatever group @ingroup defines, and the file level inclusion is not done.

2 comments:

  1. Hi mate,
    I just tried your suggestion but it sadly does not work ( at least with Doxygen 1.8.3 ). It seems that the Module section is at the same level as the Main section. Do you have any other ideas on how to achieve subgrouping ?

    ReplyDelete
  2. Sorry, can't think of any at the moment. It's a while since I needed to do anything more complex in Doxygen than just write basic comments.

    ReplyDelete