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?
