Tried Doxygen for the first time, using it to get a grip on some legacy code I have inherited. The code came embedded in a word document (lazy man's software documentation) so the first task was a simple python script to split it back into source files.
I then invoked Doxygen on it. This involved:
doxygen -g
to create the config file. I then edited the config file to set things how I wanted, e.g. disabling latex, generating documentation for internal code, enabling rtf (i.e. word 97 format). This is not hard to do, the auto-generated config file is well commented.
Then it is a simple matter of invoking it:
doxygen
Not too painful. The html documentation is nice, it includes the syntax highlighted source code hyperlinked to variable and function definitions. Apparently for C++ code it can draw diagrams of class hierarchys for extra gloss.
However, at this stage the function header comments were not included in the documentation. The original code had been commented like this:
// Do something
void DoSomething{
}
and this did not exactly match what Doxygen was expecting. It supports a few commenting standards so I modified my python script to reformat the files like this:
///
/// Do something
///
void DoSomething{
}
and this solved the problem.
The RTF file generated was 230 pages long from 23 source files (8470 lines), more than enough to blind non-programmers who cannot judge quality so are happy with quantity. Must try it on one of my projects with 198 source files sometime }
Peter's Moblog
