Had a chance today to re-visit the business of documenting code. The problem was that I was trying to make sense of some Fortran code that was not of my own making to try and port it to use GPU computing. There is a published paper that goes along with the code but going back and forth between the code and the paper seemed tedious. I was looking for a way of importing the important parts of the paper into the code (the formulas and diagrams that explain what is actually going on).
Last time I looked at this I concluded that it would be nice to use a tool like Doxygen to document code but then this is really meant for documenting code for re-use rather than documenting the code itself line by line. This morning I decided to take out my favourite editor and hack a short Python script to parse interleaved code and LaTeX commands. The result is the
docmaker program (originally called ‘makedoc’ but this clashes with a couple of programs with similar intentions). Its fully documented source code fits onto 3 pages of A4 (ok, I tweaked the margins slightly).