This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
- From: Andrew Sutton <asutton at cs dot kent dot edu>
- To: gcc at gcc dot gnu dot org
- Date: Tue, 27 Jan 2004 13:41:25 -0500
- Subject: Re: "Documentation by paper"
- Organization: Kent State University
- References: <10401271809.AA29608@vlsi1.ultra.nyu.edu>
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.
besides, limiting yourself to internal (code) documentation can pose
significant barriers to people coming on to the project (think new
contributors/bug fixers). not everybody learns from the bottom up. using
documentation generators like doxygen provides a pretty convenient way to
provide a high-level picture of the system and its components. so yes...
there is most definitely value there.
personally, i'd be for doxygen comments, but that's me and i'm just a lurker
on this list :)
andrew sutton
asutton@cs.kent.edu