Re: "Documentation by paper"

[Diego Novillo <dnovillo at redhat dot com>]

On Tue, 2004-01-27 at 14:55, Richard Kenner wrote:

> They are two very different things and you cannot derive one from the
> other.  The upper-level documentation should concentrate on such
> things as what order optimizations are done and how they interact.
> These are not things that are documented into the individual source files.
> 
We agree on that point.  And that kind of documentation is something
that could go in a single file, say gcc.c.  I am not advocating against
design documentation.  On the contrary, we need it badly.  What I'm
saying is that we can have it together with the source code.


>     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.
> 
> I don't see this.  I don't understand how duplicating the low-level
> information that's in each file into a master document would improve the
> documentation quality of GCC.
>
You can have it cross referenced from the high-level documentation.  

> But from an *API* point
> of view, it's very simple: you call a function of a certain name and it
> does a certain optimization.
>
And so, you would tell your tool to extract that one single function.


Diego.