This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: Undocumented source files
- From: Phil Edwards <phil at jaj dot com>
- To: Fergus Henderson <fjh at cs dot mu dot OZ dot AU>
- Cc: Geoff Keating <geoffk at geoffk dot org>, "Joseph S. Myers" <jsm28 at cam dot ac dot uk>, gcc-patches at gcc dot gnu dot org
- Date: Fri, 22 Nov 2002 13:29:43 -0500
- Subject: Re: Undocumented source files
- References: <Pine.LNX.4.33.0211220022130.630-100000@kern.srcf.societies.cam.ac.uk> <jm7kf6jf3m.fsf@desire.geoffk.org> <20021122071953.GA3120@ceres.cs.mu.oz.au>
On Fri, Nov 22, 2002 at 06:19:53PM +1100, Fergus Henderson wrote:
> On 21-Nov-2002, Geoff Keating <geoffk@geoffk.org> 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?
*cough*doxygen*cough*
> 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;
*cough*doxygen*cough*
> 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.
*cough*thisproblemhasbeensolvedbefore*cough*
Phil
--
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