Post History

Source: https://writers.stackexchange.com/q/25587
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

We use [doxygen](http://www.doxygen.nl/) to generate API (reference) documentation for our code. We have a small Java API and a large C++ API. The usual tool of choice for Java APIs is Javadoc, but doxygen can do both and we have decided to use a single tool for both.

With Javadoc you can add an overview for any package by adding a specially-named file to the source code. Javadoc then shows this overview, with as much documentation as you care to include, along with the documentation for the individual classes. Package overviews are useful for explaining how groups of related classes are intended to be used together, and can include diagrams, examples, and more. Because they're part of the Javadoc build, they can link to individual classes (or methods or other members).

How do I do the equivalent in doxygen, for both Java packages and C++ namespaces (which we use [kind of like packages](https://stackoverflow.com/a/2108209/922300))? I know I can edit the main page, which functions as an overview of the entire API, but I want to distribute the documentation more. I don't want one overview page; I want one overview page per logical code partition, and I want that overview to be in the same directory as the code (where it'll be more likely to be kept up to date).

Is there a way to do this with doxygen, or am I going to have to write my own tools to add files to the doxygen output?

Original score: 3