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?