This is the mail archive of the
mailing list for the GCC project.
Re: Undocumented source files
- From: Fergus Henderson <fjh at cs dot mu dot OZ dot AU>
- To: Geoff Keating <geoffk at geoffk dot org>
- Cc: "Joseph S. Myers" <jsm28 at cam dot ac dot uk>, gcc-patches at gcc dot gnu dot org
- Date: Fri, 22 Nov 2002 18:19:53 +1100
- Subject: Re: Undocumented source files
- References: <Pine.LNX.email@example.com> <firstname.lastname@example.org>
On 21-Nov-2002, Geoff Keating <email@example.com> wrote:
> Do we really need to have separate documentation (that is, outside the
> source files themselves) of the contents of each file?
> What purpose does this documentation serve?
It is very helpful for newcomers to have an overview of the whole system.
It makes it much easier for them to figure out which parts of the system
they want to explore in more detail.
> If it is desired to have separate documentation, why can't it be
> generated from the initial line of each file?
The separate documentation should be not just be a single line per module
in alphabetical order. Rather, it should be structured and ordered so
that files which are closely related conceptually are documented together;
for example, compiler passes should be documented in the order in which
the compiler invokes them, and grouped according to which main data structure
(tree, RTL, etc.) they traverse.
It would be OK for the summary documentation for each module to be
included in comments at the top of that module, but there would still
need to be a separate file containing an entry for each module,
to indicate where each module should go in the overall summary.
Fergus Henderson <firstname.lastname@example.org> | "I have always known that the pursuit
The University of Melbourne | of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh> | -- the last words of T. S. Garp.