On Tue, Feb 20, 2001 at 03:49:44PM +0000, David Mitchell wrote:
> 4. Are we all agreed that in addition to anything else (eg rfc281), at
> least some of the standard commentary should appear actually within the
> src file itself?
quote from someone recently "separate documentation is no documentation"
(sorry, forget who) which seemed a nice way of describing it.
I think it would be good to make it so easy to documented code as you
write it that there really would be no excuse not to do it
> 5. Does anyone agree or disagree with my proposal for mandatory
> per file, per section, and per func/struct comments?
Tolkien quotes are mandatory?
perl5's globals.c malloc.c perlio.c perly.c universal.c xsutils.c
definitely fail then.
[globals.c malloc.c miniperlmain.c perly.c regcomp.c regexp.c taint.c
universal.c xsutils.c have no copyright statement.]
embed.pl doesn't add a Tolkien quote or a copyright statement to perl API.c
> 5. Do *all* these comments need to be extractable, or only ones related
> to published APIs etc?
You have 2 point 5s.
[I feel there must be a Monty Python quote related to this, but apart from
"Rule 6 - there is /no/ rule six" from the Bruces sketch, I'm lost]
It would be good to be able to extract documentation relating to the
implementation behind the APIs, for guts hackers.
> PS. I decree that this email solves Warnock's Dilemma [*] by assuming
> that silence implies absolute assent to everything I have ever said or
> will ever say..... ;-)
I don't think "will ever say" holds. And I think I'd phrase it as
"ongoing silence". But apart from that, it seems to be a working
assumption for design proposals.
Nicholas Clark
