Visual Assist X and doxygen
For people still working with C++ in Visual Studio, it may be a bit bizarre that there is no easy way to document your functions, methods and classes with a single keypress. By this I mean the auto generated lexicon of all code constructs, filled with information that comes from specially formatted comments. Imagine this situation: you're coming back to your old project and found function prototype like this in some header:
int InvalidateCrossReferences(Node * root, bool firstMethod = false);
Do you know what it does? How does the second argument affect it result? Is it thread safe? Is it throwing exceptions? What value is returned?
Of course you can look through code and spend next 5 minutes to figure that out, but it would be a lot faster if you have written this:
/* This set "invalid" flags on every tree node that is referenced from within the tree The first method is O(n^2), but is actually faster for small trees (<20 nodes) Returns number of nodes invalidated */ int InvalidateCrossReferences(Node * root, bool firstMethod = false);
See? Much easier now. But it still isn't that generic! We want entire project documented, and to do so, all comments must share the same layout. Then we can run the special tool, called documentation generator which will read through all sources and compile comments with code into chm/html/pdf/whatever you want.
Arguably, the most complete documentation generator for C++ is Doxygen, available for free from here: www.doxygen.org
You can generate it from completely comment-less code and still get results that helps to work on old, or someone else's project. Of course you can, and should, use it to document your own code.
As doxygen comments tends to be a bit complicated, I created the following Visual Assist X snipped, that helps to create this. If you have Visual Assist X plugin installed in your Visual Studio, just click
Then pick C++/Refactor Document Method and put this:
/** * @brief Put brief description here * * Put full description here * * @param[in,out] $MethodArgName$ Put argument desc here * @return Put return information here */
(Don't forget the trailing newline!)
Accept, then right click your function and choose Refactor (VA X) -> Document method and voila - you get doxygen ready comment!