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?

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.)

Answer 2

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.stack.nl/~dimitri/doxygen/commands.html#cmdnamespace