This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
- From: Diego Novillo <dnovillo at redhat dot com>
- To: Richard Kenner <kenner at vlsi1 dot ultra dot nyu dot edu>
- Cc: asutton at cs dot kent dot edu, "gcc at gcc dot gnu dot org" <gcc at gcc dot gnu dot org>
- Date: Tue, 27 Jan 2004 14:26:53 -0500
- Subject: Re: "Documentation by paper"
- Organization: Red Hat Canada
- References: <10401271855.AA00249@vlsi1.ultra.nyu.edu>
On Tue, 2004-01-27 at 13:55, Richard Kenner wrote:
> 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.
>
> I strongly agree that having high-level documentation is important, but
> I don't see that documentation generators produce it!
>
Not 'produce', 'extract'.
If such high-level documentation is written inside a comment at the top
of each file, then you can coax the publishing tool of your choice to
emit it in a dozen different formats.
If folks don't care for having formatting markes in the comments, that's
fine with me. But it is possible to extract documentation from the
source code directly, and that is what I would like us to do for the
internal API and design documentation, at least.
Diego.