Documenting namespaces that span multiple files doxygen

Question

Consider I have 2 header files.

// HEADER 1
/**
 * Doc  for Foo here?
 */
namespace Foo {
  class This {...};
}

&&

// HEADER 2
/**
 * Doc for Foo here?
 */
namespace Foo {
  class That {...};
}

How should I handle this when documenting with Doxygen?

Architect

would be a great feature for doxygen to maybe add a paragraph for each of the namespace documentation piece per file. All suggested solutions feel more like crutches to compensate for the tool deficiency. – Physiography

Answer 1

Maybe neither.

For example, imagine you have "<root>/utility/header1.hpp" which has its contents in namespace utility and "<root>/utility/header2.hpp" which does also.

You could add a file: "<root>/utility.hpp" which documents the utility namespace. You could put this at the top #error Documentation only. to make sure it's not accidentally included.

But I would recommend at least making some out-of-the-way file to keep it in a sane place (and not mixed in randomly with some class.)

Lanell

You don't need to have a special file for every namespace. You could use a global "project documentation" file that supplies the front page docs for your project, sets up the groups (for use with /ingroup tags), and documents the namespaces all in one place. This allows all the "overviews" to be held in one logical place rather than scattered to the winds. You could even put this core documentation in a "documentaiton" folder which also contains things like your doxygen configuration files etc. – Brosy

@Jason After reading this answer that was actually what I was leaning towards. Sounds like a good plan. – Architect

@JasonWilliams: I think your proposal is worth an own answer. I believe this is the better approach. – Enstatite

Answer 2

I have placed documentation for namespaces that span multiple files into another file. My Doxygen builds use a separate file for the @mainpage tag. This forms the root of the built Doxygen, and is also a central location for such namespaces.

So I'll have project_name_mainpage.h, and in that file:

/**
@mainpage title
...whatever you want to tell the user about your application...
*/

/**
 * @namespace your_namespace
 * @brief An awesome description
 * @details More sweet details
 */

Keeps it all in one place, and is relatively easy to find if you need to update it.

Kristy

Answer 3

Find the best place for the documentation, whether it is in one of those files or another entirely. Use a comment block with Doxygen's namespace tag:

/**
 * @namespace Foo
 * Documentation for Foo here. More docs for Foo here,
 * and down here.
 */

Docs here: http://www.doxygen.nl/manual/commands.html#cmdnamespace

Tineid