Re: Thoughts on doxygen for internal documentation

[Kurt Wall <kwall at kurtwerks dot com>]

Feigning erudition, Diego Novillo wrote:
% On Thu, 16 Jan 2003, Jeff Law wrote:
% 
% > Actually, I wouldn't go with doxygen stuff at all unless it's been
% > OK'd for the rest of the compiler proper.
% > 
% Oh, well, OK.  In reality all I we *really* need is to delimit
% comments with /** */.  All the rest is up to doxygen to figure
% out.  So, even if the comments are not delimited with /** */,
% doxygen is still useful.
% 
% Let me rephrase the question then.  Would it be OK to start
% documenting major functions and data structures with /** */
% instead of /* */?
% 
% I will still request its usage in tree-ssa-branch.  If the final
% decision is not to use the additional '*' in comments, a sed
% script can easily remove them from the tree-ssa files before we
% merge to mainline.

Not that my vote counts for anything, but I would oppose 
doxygenification for (at least) two reason. First, I don't find 
doxygen'ed documentation particularly illuminating to read -- I can 
just as well read the source code and the header files if I need
API references. If one takes the time to write meaningful, useful
documentation in the code using /** */, then the desired goal, 
writing useful documentation, is already achieved. If, on the other 
hand, inaccurate comments or downright useless comments are embedded 
in a doxygen-friendly way (that is, using /** */), then all you've 
achieved is creating lousy documentation that is easy to extract
and format nicely. ;-)

Secondly, and let me be clear that I'm not referring to anyone in
particular, doxygen and similar automated methods of documenting
code speak more to laziness and sloppiness than to producing high
quality documentation. Of course, manual^H^H^H^H^H^Hinfo pages can
be just as poorly written as automatically-generated documentation,
but one has to try harder to write lousy documentation when creating
an info file from scratch -- doxygen and kin just make it easier to
create awful documentation.

My two farthings...

Kurt
-- 
A diplomat is a man who can convince his wife she'd look stout in a fur
coat.