[svn ci] PMC documentation guidelines draft

6 views
Skip to first unread message

Jerry Gay

unread,
Apr 5, 2007, 10:32:31 AM4/5/07
to p2
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.
~jerry

Klaas-Jan Stol

unread,
Apr 5, 2007, 11:45:33 AM4/5/07
to jerry gay, p2
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
* usage: to indicate how people should (and should not) use the pmc
* author: so people know who to blame for the pmc (or praise!)
> ~jerry
>
kjs

Joshua Isom

unread,
Apr 5, 2007, 1:51:11 PM4/5/07
to Klaas-Jan Stol, p2
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?

Klaas-Jan Stol

unread,
Apr 5, 2007, 2:39:10 PM4/5/07
to Joshua Isom, p2
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
Reply all
Reply to author
Forward
0 new messages