Doxygen (Was: Re: "Documentation by paper")

[Matt Austern <austern at apple dot com>]

On Jan 27, 2004, at 10:41 AM, Andrew Sutton wrote:

> On Tuesday 27 January 2004 01:09 pm, Richard Kenner wrote:
> >     Which reminds me.  What happened to the proposal that was 
> > discussed in
> >     the last GCC summit to start adding doxygen markers to the source 
> > code
> >     comments?
> >
> > I'd be very strongly *against* such a proposal.  I don't see anything 
> > but
> > the slightest advantage of such "external" documentation, certainly 
> > not
> > worth cluttering up code with "markers".
> >
> > If there is a value to having such external documentation, let's 
> > teach it
> > how to read GCC's documentation style, which already has enough
> > information.
>
> just a quick point of reference... almost any documentation on the 
> topic of,
> well... documentation basically says that external documentation is a 
> very,
> very good thing to have - there are whole academic conferences on the 
> topic
> (SIGDOC, DocEng, etc.) and this turns out to be quite a big topic in 
> software
> maintenance/evolution and program understanding.

I agree that external documentation is useful.  I am not convinced that
external documentation produced by processing comments in source
code is the best kind.  External documentation, to be useful, should be
complementary to source code comments.  It should focus on "big
picture" issues: not the individual interface of one particular 
function or
struct, but issue like how the different pieces interact, where you 
should
start looking first, and so on.  I've seen a lot of lousy documentation 
that
was clearly produced by people who thought that all they had to do was
produce localized documentation for each individual piece.

I don't think that doxygen is harmful by itself, but I think it would be
harmful if people start thinking that it's a substitute for other kinds 
of
external documentation.

			--Matt