This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Undocumented source files


On 21-Nov-2002, Geoff Keating <geoffk@geoffk.org> wrote:
> 
> Do we really need to have separate documentation (that is, outside the
> source files themselves) of the contents of each file?

IMHO, yes.

> 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 <fjh@cs.mu.oz.au>  |  "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.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]