Use of automatically generated docs (Doxygen) experience from another project

[rthorpe@realworldtech.com]

I recently retrofitted Doxygen documentation onto a program.  It was
much smaller than gcc, but I can tell you what I found.  If your not
interested in the experiences of a random lurker stop reading now.

I found:

Comment obfustication

Doxygen markup need not disrupt the comments, if you use it
selectively.  I ignored @param and @return, I only used /** and @file
at the top of files.
Avoiding @param and @return doesn't make it much less useful either.
It would take years to annotate gcc's comments with @param and
@return anyway.

Documentation usefulness

I didn't find the generated docs very useful.
The reasons are:

1) Function and variable comments aren't really as useful as Emacs M-.

2) The docs extracted from the comments heading the files describing
them turned out to be the most useful.  But they were often too
detailed or too simple (or both).  So when I needed to describe the
high level design of the program I wrote a separate document.

3) Lists of functions aren't as useful as header files (but in my
case the header files were very clear).

3) Doxygen is very C++ orientated.  Also, in C++ there are many more
types of things, so doing much more classification is appropriate.

4) Quite often you get a really puzzling piece of Doxygen output with
too much info on it to understand.

Strangely enough the most useful thing was looking at which functions
called which others, that gave me a better idea of where modules were
too highly coupled.