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