On Jun 6, 2007, at 10:08 AM, Ian Malpass wrote:
I've been documenting lately, so I'm a bit POD-focussed at the
moment :) I was pondering creating Pod::Critic, as a documentation
analogue of Perl::Critic.
Clearly it's not so easy to give hard-and-fast rules about
documentation, but I thought it might be useful as a framework for
enforcing internal documentation standards and "house styles", even
if it didn't ship with many policies itself.
Policies I've thought of:
* Has NAME
* Has SYNOPSIS
* Has copyright details
* Has license details
* Method docs have examples
* No spelling errors (borrowing Pod::Spell)
Other more vague/less useful ones, perhaps:
* Module names are links
* Method names are in C<> sequences
I think this would be good, especially because I could make it
optional to use it in Test::Pod.
I've had people ask for many of the bullets above as items to trigger
failure in Test::Pod, but I've always resisted, because I don't want
to make it mandatory. However, if you made it Pod::Critic adequately
hookable, then I could make it an option, and people could be happy.
--
Andy Lester => [EMAIL PROTECTED] => www.petdance.com => AIM:petdance
