4

Consider several C++ classes which are all defined in a particular namespace. For cleanliness, each class is located within its own file, and are each well-documented.

For the purposes of completing the documentation with Doxygen, we'd also like to add documentation for the namespace itself.

Does anyone have any suggestions for a good best-practice solution for this? We've got a couple of options:

  • A dedicated namespace.h file which contains only the namespace and the documentation for it. This means there is a single location to describe the namespace, but does mean having a seemingly purposeless file.
  • Add the description for the namespace inside one of the class files (such as the most significant one?). This means not having to add a new file, but does make it harder to find the description if there ever is a need to modify it.
Improve this question
2
  • 1
    The documentation file is not "purposeless" - it is for documentation.
    – BobDalgleish
    May 31, 2019 at 16:38
  • @BobDalgleish True. I meant "purposeless" purely in terms of code compilation and not for anyone reading it. Its presence, though beneficial in terms of documentation, does also contribute to the number of relevant header files and therefore to the "noise" which the developer needs to get their head around.
    – John Go-Soco
    Jun 3, 2019 at 8:12

1 Answer 1

Reset to default
2

Generally speaking, for most libraries, you'll have a single header that includes all of the other files of interest in your library. Or at least, the majority of them.

That's a good place to document the namespace, even if that file never directly uses it. Just create an empty namespace Name {} declaration.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.