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
Some or all of these may not be relevant for particular instances,
and I suspect it'll be less common to use an out-of-the-box set of
policies.
Anyone got any thoughts?
Ian
As Nadim said, several of these are already implemented in
Perl::Critic. It's fairly straightforward to write new policies for
Perl::Critic, so I recommend you give that a try. The module name
and method name ones would be particularly welcome. I'd be happy to
review any policies you write.
The Perl::Critic mailing lists:
http://perlcritic.tigris.org/servlets/ProjectMailingListList
(the dev one has the most traffic)
Perl::Critic developer tutorial:
http://search.cpan.org/dist/Perl-Critic/lib/Perl/Critic/DEVELOPER.pod
Chris
--
Chris Dolan, Equilibrious LLC, http://equilibrious.net/
Public key: http://chrisdolan.net/public.key
vCard: http://chrisdolan.net/ChrisDolan.vcf
