Make sure you have the latest version of this memo.
Version Date: September 22, 2016.
Type of Memo: Informative
I like documentation that reads like a story. Like, you know,
Once upon a time there was a nice smart brave C++ class called Minimizer who set out on a journey to find ...
Although, Minimizer will always be nice, smart and brave, other parts of its documentation might change with time. So the problem becomes that such documentation would be written separately from the code, and (i) will become out-of-date pretty soon, and (ii) will be tedious to maintain in sync with what the code actually does.
So, Knuth (of TeX fame) suggested Literate Programming, that is, writing a .w file in human format and then getting from it two files: one for the code and one for the documentation. Apart from having the documentation tied to the code, the advantage here is that one can develop a story for the documentation. The disadvantage with this, though, is that tools (IDE, debugger, valgrind) don't understand .w files.
On the other hand, we have things like doxygen where one is supposed to write documentation in the code as comments and then one is supposed to extract said documentation from the code. The advantage is that now files like .h and .cpp are the usual ones and all tools understand them. The problem, though, is that doygen will produce an API-like or library-like documentation, which doesn't fit a storyline documentation.
Once upon a time there was a nice smart brave C++ class called Minimizer who set out on a journey to find the minimum of a function for a given range and maximum number of iterations. This class takes two template arguments RealType and FunctionType. Its member function simplex is the one that actually performs the minimization using the simplex method, by setting its first argument with the vector that minimizes the function. The other arguments are the delta and the tolerance.
Now to simplify keeping documentation and code in sync, what needs to be said about class Minimizer better be said in class Minimizer, and, likewise, what needs to be said about function simplex better be said near that function as well, as shown in this listing.
/* PSIDOC Minimizer find the minimum of a function for a given range and maximum number of iterations. This class takes two template arguments RealType and FunctionType. */ template<typename RealType,typename FunctionType> class Minimizer { ... /* PSIDOC MinimizerSimplex performs the minimization using the simplex method, by setting its first argument with the vector that minimizes the function. The other arguments are the delta and the tolerance. */ int simplex(VectorType& minVector, RealType delta=1e-3, RealType tolerance=1e-3) { ... } };
So, now the storyline can use hooks to the embedded code, like
Once upon a time there was a nice smart brave C++ class called Minimizer who set out on a journey to \ptexPaste{Minimizer} Its member function simplex actually \ptexPaste{MinimizerSimplex}
Now, putting it all together the recipe for writing and extracting documentation is
cd dmrgpp/doc find ../src -iname "*.h" -or -iname "*.cpp" | perl ../../PsimagLite/scripts/doc.pl manual.ptex
Here are further things I wanted to say but would have distracted from the main points.