This is the mail archive of the
mailing list for the GCC project.
Re: "Documentation by paper"
- From: kenner at vlsi1 dot ultra dot nyu dot edu (Richard Kenner)
- To: dnovillo at redhat dot com
- Cc: gcc at gcc dot gnu dot org
- Date: Tue, 27 Jan 04 14:55:25 EST
- Subject: Re: "Documentation by paper"
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.
No, that's not the level of documentation we're talking about!
The comments in each file describe what each file does at the high
level. What high-level documentation of GCC would consist of is an
overview of what the files do when put together. That is not at all
the same as a concatenation of all the high-level comments in file.
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.
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 make the API argument, but even
that's weak. Consider the optimizers, for example: you may have a 10,000
line source file that goes into extensive detail on on optimization
algorithm and has dozens of internal functions. 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.