How to mirror C directory structure using Doxygen groups?

Question

I need some basic help using Doxygen in C code. All basic documents look great, and I want to help structure a long, long list of files and functions.

I have a source C tree that looks like this:

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

Very standard. Doxygen currently generates a flat file list of all files. We refer to every dub-dir src / as a “module”, and therefore documenting this seems to be good compatibility with Doxygen modules / groups.

How exactly should I use grouping commands to mirror the directory structure above? I want the module to be used in generated documents that reference documents file1 and file2. Just like JavaDoc will handle the package.

Adding the / addtogroup util and @ {tags to each header file created a mini-site with a flattened list of all data structures, etc. in all the headlines, which I did not expect or did not want. Perhaps this is what doxygen groups should do, i.e. Document API evenly when code is implemented across multiple files?

Answer 1

The easiest way to use modules is to use @page and @subpage . To get something similar to your described layout, you can 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 in many. Usually I put @page file1 in file1.h, @page file2 in file2.h, etc. And @subpage comments in a more top-level header or main source file.