Front page | perl.perl6.internals |
Postings from February 2001
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 ClarkThread Previous | Thread Next