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: Daniel Berlin <dberlin at dberlin dot org>
- Cc: Robert Dewar <dewar at gnat dot com>, Zack Weinberg <zack at codesourcery dot com>, "gcc at gcc dot gnu dot org" <gcc at gcc dot gnu dot org>, Joe Buck <Joe dot Buck at synopsys dot COM>, Richard Kenner <kenner at vlsi1 dot ultra dot nyu dot edu>, Diego Novillo <dnovillo at redhat dot com>, lars dot segerlund at comsys dot se
- Date: Sun, 1 Feb 2004 01:13:47 -0500
- Subject: Re: "Documentation by paper"
- Organization: Kent State University
- References: <10401271550.AA28749@vlsi1.ultra.nyu.edu> <4F8BA8CE-50F7-11D8-9C84-000A95DA505C@dberlin.org> <401C3E5D.7060402@gnat.com>
> > Is there anyone *except* Richard Kenner who is against this?
>
> Yes, me. I agree with Richard on this, I don't see any
> significant advantage in the separated documentation. In
> fact I suspect it in practice has the negative effect of
> out-of-date documentation wandering around.
>
> I would certainly not pay even a minimal obfuscation cost
> in the sources for this. For one thing, it makes it harder
> work to keep the documentation up to date in the sources.
> Given most people's attitude to documentation, it is hard
> enough to get people to keep doc up to date without putting
> additional roadblocks in the way.
just a lurker's comment, but i think the point that several people were trying
to make was that you can write a relatively static overview and use something
like doxygen to keep the specifics of the api up to date. it shouldn't be
that hard to document your functions.
andrew sutton
asutton@cs.kent.edu