Ian Malpass wrote:
Policies I've thought of:
* Has NAME
* Has SYNOPSIS
* Has copyright details
* Has license details
You mean licence :-) Although I see that's been fixed in CPANTS now so
at least that bit could share code.
* Method docs have examples
That's going to get really boring really quickly, and putting in
pointless examples just to satisfy this would hinder the reader in his
attempt to quickly figger out what he needs to do, simply by wasting
screen space:
METHODS
foo
Returns one or zero depending on whether your object can foo:
$thing->foo();
bars
Tells you how many bars your object has visited this evening:
$thing->bars();
barf
Tells your object to barf on its own shoes:
$thing->barf();
* No spelling errors (borrowing Pod::Spell)
One man's spelling error is another's code example. creat(), anyone?
And no, you can't tell what's a code example and what's not by looking
at how it's laid out. Consider these sentences:
The 'creat' function is a less capable version of 'open'.
When we say 'create' we really mean 'insert'.
Other more vague/less useful ones, perhaps:
* Module names are links
* Method names are in C<> sequences
Again, a method name may also be a perfectly legitimate word in whatever
language the author is using, and so appear in all sorts of other places.
--
David Cantrell
