[Wikitech-l] Some notes on Doxygen

Tels wrote: Brion Vibber wrote: I haven't used Doxygen with PHP, so I don't know how much it is able to extract from PHP code. However, here are some notes, based on my experience using it (a few years ago) with C code: * There are assorted options that can be turned on. One option I like is the one that turns on clickable (image-mapped) context diagrams. These are generated by the dot(1) program of the Graphviz suite. The XML output option can be useful, if anyone wants to do analysis of the extracted information (I might :-). * Although Doxygen can extract some information from the code, it really starts to shine when the programmers have added some mark-up. This consists of specially-formatted comment blocks, placed just before the code that defines data structures, functions, etc. Here's an example: /*! \brief Brief description. * Brief description continued. * * Detailed description starts here. */ The "\brief" tag is one of several dozen that can be used to specify particular information. Common tags include \def, \file, \fn, \param, and \var. The more information Doxygen is given, the better documentation it can produce. * Doxygen is quite customizable. If you don't like the way the pages look, it's not that hard to change them. Of course, this will saddle you with maintenance issues when Doxygen gets updated... * The Doxygen manual is quite extensive (132 pages) and very readable. I have also found the author to be responsive. Finally, there is an active mailing list. For more infor- mation, visit the Doxygen web site: http://www.stack.nl/~dimitri/doxygen/ -r -- http://www.cfcl.com/rdm Rich Morin http://www.cfcl.com/rdm/resume rdm(a)cfcl.com http://www.cfcl.com/rdm/weblog +1 650-873-7841 Technical editing and writing, programming, and web development