I have a small project written primarily in C++ which is documented with Doxygen and tested with a unit testing framework (Google Test in my case, but that doesn’t matter). I wrote several test cases for each method of each class to test the method’s behavior under various conditions, and I want to leave some comments for the test suites. The Doxygen documentation is designed for projet’s user, who very likely does not want to see the documents for projects implementation details and tests.
I want to know what is the common strategy of unit test documentation? Do not comment them at all and consider the tests themselves as documentation?
Or maybe leave non-doxygen comments in the test files? Or use doxygen’s
ENABLED_SECTIONS option to compile test documentation conditionally?
ENABLED_SECTIONS is the way to go. Then you can easily switch them on for those who want them (yourself, colleagues, maintainers) and off for those who don’t (the project’s user).
That’s what we do & it works just fine.