develooper Front page | perl.perl6.internals | Postings from February 2001

Re: PDD for code comments ????

Thread Previous | Thread Next
David Mitchell
February 20, 2001 07:51
Re: PDD for code comments ????
Message ID:
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:


Whereas I'm about to say....


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

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 Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About