This is the mail archive of the 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 Fri, Nov 22, 2002 at 06:19:53PM +1100, Fergus Henderson wrote:
> On 21-Nov-2002, Geoff Keating <> wrote:
> > 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.

Absolutely.  The more of this, the better.

> > 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;


> 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.



I would therefore like to posit that computing's central challenge, viz. "How
not to make a mess of it," has /not/ been met.
                                                 - Edsger Dijkstra, 1930-2002

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