This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
- From: Paul Koning <pkoning at equallogic dot com>
- To: kenner at vlsi1 dot ultra dot nyu dot edu
- Cc: zack at codesourcery dot com, gcc at gcc dot gnu dot org
- Date: Mon, 9 Feb 2004 13:59:17 -0500
- Subject: Re: "Documentation by paper"
- References: <10402091858.AA08128@vlsi1.ultra.nyu.edu>
>>>>> "Richard" == Richard Kenner <kenner@vlsi1.ultra.nyu.edu> writes:
>> Weird, I thought you didn't like extracting documentation
>> from the source code.
Richard> I don't like *automated* extraction, but there's nothing
Richard> wrong with a human rewriting code documentation to the level
Richard> appropriate for an internals manual.
An internals manual has indexing (or at least it can, and should).
How do you do that in code docs?
In my experience, a major problem with gcc -- unless you've been
working on it full time for at least 5 years -- is that it's so
complex that it's nearly impossible to get started. The internals
manual helps a little, though its indexing and cross-referencing isn't
nearly good enough. If the internals manual is deprecated in favor of
/* ... */, I fear this problem will get much worse, not better.
paul