Front page | perl.perl6.internals |
Postings from February 2001
Regarding comments in code: Chopping and misquoting wildly.... Jarkko Hietaniemi said: * I would define a relatively strict and standard way to do this so that the documentation can be extracted out. * lets avoid a markup-up flamewar Simon Cozens said: * I'd like to see Perl 6 written as a literate program * the apidoc is a really good thing, but it needs to be made more extensible * RFC281 was an initial set of thoughts on this idea. David L. Nicol said: /* =pod =cut */ Whereas I'm about to say.... Questions: 1. Does anyone *disagree* that we need "a relatively strict and standard way" to document code? 2. Is this the time and place to discuss it? 3. Should the result of the discusssion be a PDD? 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? 5. Does anyone agree or disagree with my proposal for mandatory per file, per section, and per func/struct comments? 5. Do *all* these comments need to be extractable, or only ones related to published APIs etc? 6. Can we leave the details of pod/apidoc/rfc281 until 1..5 have been agreed? 7. What is the average air speed velocity of a swallow, etc etc... Dave M. 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..... ;-) [*] Or should that be quintlemma, or pentlemma, or ....? Any Classics scholars out there?Thread Previous | Thread Next