Documenting classes with doxygen (I want a birds eye view of the code but also want documentation)

Question

When I code in plain C there is quite a beautiful interaction between headers and c files in terms of documenting the code.

I tend to add the documentation on the cc files (and yes I am aware that most people prefare them in the headers), but by doing this my header is now a birds eye view of the cc file. I can, at a glance inspect large chunks of information about what is defined in the file.

For C++ classes this is even more useful, since I often want to see the private members of a class to give me an idea of what the class is meant to represent.

However if you start documenting every member within it, you now have large spacing between member variables filled with comments and no way to get a bird's eye view of the code.

What alternative could I use?

Answer 1

Doxygen supports various ways to place your documentation comments, not just the big block before a declaration or definition.

Some ways to have documentation comments and keep your declarations together without intervening comment blocks are:

• Use trailing documentation comments after (member) variables and/or enumerators:

  int var; /*!< Detailed description after the member */
  

• Place the documentation for member functions with the out-of-class definition of the function
• Use doxygen commands like \class, \fn or \var to link the comment block to the element it is documenting, rather than the placement of the comment block. For functions and variables, this has the drawback that you have to duplicate your declarations (once in the code and once in the comment block) and that it is not obvious if something has been documented or not.

Besides these options, many IDE's also have features to collapse various structures, like comment blocks, in such a way that they become unintrusive for looking at the actual code.