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.
~jerry
> 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?