Documenting namespaces that span multiple files doxygen

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