Re: Pod::Critic?

[Ian Malpass]

David Cantrell wrote:

    * Has license details

You mean licence :-) 

DAMMIT.

    * 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:

You're right, of course, and I'm not sold on this policy myself either. 
I was envisaging a "no critic" option a la Perl::Critic, which would at 
least mean that the developer had deliberately not included an example. 
It's very much a "house style" type of policy. Might be a bad house 
style, though....

    * 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. 

Hence Pod::Spell's stopwords.

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.

Again, possibly assuaged by the "no critic" pseudo-pragma and/or some 
policy config or =for/=begin config option.

Your points are some of the reasons I'm not sure Pod::Critic is a 
workable idea.

It's not possible to be as specific for documentation as PBP can be for 
Perl, and I can't imagine any particular policy being suitable for 
everyone. That doesn't mean that no policies are suitable for anyone, 
though.

Ian