On Apr 5, 2007, at 10:45 AM, Klaas-Jan Stol wrote:
jerry gay wrote:
i've recently committed (r17998) a draft of PMC documentation
guidelines, for your review. This document is meant to formalize,
clarify, and extend the current de facto style for documentation of
core PMCs. you'll find the document at docs/pmc/documentation.pod.
highlights:
~ brings many things which are currently c-style comments into pod,
which makes the information more accessible
~ groups related items together, making for easier reading
~ provides better descriptions of functions and methods, making the
PMC user's life easier
~ adds stability classification to PMCs
your comments, questions, patches, and commits are most welcome.
As mentioned on #parrot, it misses how to use the thing. "Perl Best
Practices" has a nice template, from which some sections could be
stolen:
* version: always useful, as things *will* change in the future
Which version? The parrot version, or the revision, etc? Although it
won't end up in any pod, the last revision is stored at the top of the
fine, line three.
* usage: to indicate how people should (and should not) use the pmc
Often people have to abuse something before you know to tell them not
to use it that way. Do you have specific examples?
* author: so people know who to blame for the pmc (or praise!)
~jerry
kjs
