Joshua Isom wrote:
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.
The version of the PMC; PMCs will be updated (as implementations will
change over time). It's just the same as PDDs: they have a version, why
not give other 'documents' a version.
* 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?
well, this is kinda obvious, isn't it? Just as the synopsis for a perl
module, which tells you how to use the module (for instance, how to use
recdescent parse module), this usage tells you how to use the pmc. In
many cases it's very simple (Integer, etc.), but others (Exporter) are
not self-evident.
IMHO, it's good to tell the user what the expected/typical use is.
* author: so people know who to blame for the pmc (or praise!)
~jerry
kjs
kjs
