On Wednesday 06 June 2007 17:08, 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
97%of this exists already through test::Spelling or Perl::Critics (see RequirePodSections). 'method docs have examples': I believe the examples should be tested. for that, Test::Inline, Test::Pod::Snippets, or my favorit,Test::Cookbook can be used (as a base, let me know if you are really serious about that one) . Also private API may not need those examples. If you come with a system to 'tag' the private API's please refrain from forcing everyone to prepen an eye poking '_' before the method name. A list as Test::Spelling uses is so much nicer. I believe a much better approach to the 'have an example for each API' is to have a cookbook and run coverage on the tests within the cookbook. Here I think about a big bigger modules that may have more documentation than a reference manual. Those tests are going to take longer to run. I would prefere to see rules in Perl::Critics than a new module. In any case, this is a very good idea as the properly documeted Perl module is becoming a rarity. As for 'well' documented modules, it's an art I'd like to learn. Cheers, Nadim.
