How to mirror C directory structure using Doxygen groups?

Question

I need some basic help using Doxygen on C code. All basic docs are coming out fine, and I want help structuring the big long long list of files and functions.

I have a C source tree which looks like this:

src/
 +--util/
    +--file1.h
    +--file1.c
    +--file2.h
    +--file2.c
 +--stats/
    +--file3.h
 +--etc/

Very standard. Currently doxygen generates a flat file list of all files. We refer to each dub-dir of src/ as a 'module', and so documenting this seems like a nice fit for Doxygen modules/groups.

How exactly should I use the grouping commands to mirror the directory structure above? I want to have a module util in the generated docs which links to the file1 and file2 docs. Exactly like JavaDoc would treat a package.

Adding the /addtogroup util & @{ tags to each header file generated a mini-site with a flattened list of all data-structures etc within all the headers, which isn't what I expected or wanted. Perhaps this is what doxygen groups are supposed to do though, ie, document an API uniformly when the code is implemented across multiple files?

Answer 1

A simpler option to using modules is to use @page and @subpage. To get something similar to your described layout you could use the following:

@page util Util
This page describes util module.
@subpage file1
@subpage file2

@page stats Stats
This page describes stats module.
@subpage file3

@page etc
Blah blah blah

@page file1 File 1
This is file 1.

@page file2 File 2
This is file 2.

@page file3 File 3
This is file 3.

These comments can of course be contained in one file or many. Typically I'd put the @page file1 in file1.h, @page file2 in file2.h, etc, and the @subpage comments in a more top-level header or main source file.