[Design] help? review documentation autogenerators

[Andy Dent]

At 12:02 -0800 28/02/2003, Kaitlin Duck Sherwood wrote:
>Has anybody used software that creates documentation from source code,
>e.g. JavaDoc and Doxygen?
..
<http://wiki.osafoundation.org/bin/view/Main/CodeToDocumentationSoftware
updated but for those who don't do wiki...

I added a link to http://epydoc.sourceforge.net/ and the following discussion.

I have used doxygen extensively on my own OOFILE product reference manual
(http://www.oofile.com.au/oofile_ref/html/index.html ) and in various
client sites especially on cross-platform port projects. One of the nicest
things about Doxygen is how good a job it can do without markup (although
you have to turn off a default config of HIDE_UNDOC_CLASSES). Doxygen also
makes it VERY easy to mark code as belonging to various groups, which I've
used heavily (http://www.oofile.com.au/oofile_ref/html/modules.html )
throughout OOFILE. Even groups can be nested within other groups, making it
very easy to build a nested package hierarchy (something that Java gives
inherently as part of the language).

Marking groups is such a powerful way to improve documentation that I think
it should be a key determinant in selecting a Python tool. For example,
I've also used the @ingroup marker as a way to tag code with attributes
like volatile/nonportable etc.

-- 
Andy Dent BSc  MACS  AACM   http://www.oofile.com.au/
OOFILE - Database, Reports, Graphs, GUI for c++ on Mac, Unix & Windows
PP2MFC - PowerPlant->MFC portability