Re: Pod::Critic?

[Chris Dolan]

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

Re: Pod::Critic?

[Nadim Khemir]

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.

Re: Testing URIs in POD

[Ian Malpass]

Nadim Khemir wrote:

How do you plan to test things like:

my $url_base = "http://search.cpan.org/"; ;

for my $rest (qw(modlist/Graphics modlist/Database_Interfaces))
{
do_anything_with($ur_base . $rest);
}


Well, if it's in a verbatim block, then "http://search.cpan.org/"; would 
get tested. If it's in the code, then since this is a POD test it 
wouldn't get touched - to my mind, that's kind of up to your own test suite.


In the verbatim block, it's still not testing what you want. I could 
certainly provide a mechanism for specifying additional URLs for 
testing. In fact, I suspect


   =for test-pod-uri http://search.cpan.org/modlist/Graphics

would Just Work given the implementation I'm thinking of. Not ideal to 
have the URLs duplicated, but I can't think of a (sane) way to do 
anything else.


Ian

Re: Testing URIs in POD

[Nadim Khemir]

How do you plan to test things like:

my $url_base = "http://search.cpan.org/"; ;

for my $rest (qw(modlist/Graphics modlist/Database_Interfaces))
{
do_anything_with($ur_base . $rest);
}

Nadim.

On Sunday 03 June 2007 15:10, Ian Malpass wrote:
> ReneeB wrote:
> > Let this the POD from the (nonexistant) module Anything::URI:
> >
> > =head1 NAME
> >
> > Anything::URI
> >
> > =SYNOPSIS
> >
> >   use Anything::URI;
> >   my $url = 'http://www.example.tld';
> >   do_anything_with($url);
> >
> > ...
> >
> > In that case "http://www.example.tld"; shouldn't be extracted and tested
> > as this is just an example...
> >
> > Links to other resources should be tested, but not such examples.
>
> My plan, at least for now, is to provide the equivalent to Pod::Spell's
> "stopwords". "Stopurls" as it were. So you can pass in a list of URLs
> and/or patterns to ignore (e.g. "/example.com/").
>
> Also planning to extract URLs from all the POD - text blocks, verbatim,
> etc. - with an option to restrict it to L interior sequences. Could also
> opt to ignore verbatim optionally too.
>
> Ian
>
> P.S. I'm more than happy to be sent examples and/or test scripts, or
> pointers to extant modules that might have interesting parsing results,
> etc.

Re: Pod::Critic?

[Eric Wilhelm]

# from Ian Malpass
# on Wednesday 06 June 2007 08:08 am:

>     * Has copyright details
>     * Has license details

On bigger projects, these things sometimes get done as "see the main 
module documentation for copyright and license statement".  Thus, it 
would be good for this to be configurable as something like "has block 
$x", where $x is specified in a "pod_blocks/$x" file in the project 
tree.

Similarly, I would like overrides to be able to be specified without 
comments or other markers in the code.  Maybe a yaml file of 
module/method settings.  (I'm imagining that I'll one day be reading a 
file with critic+pod_coverage+pod_critic+tidy markup in it and my eyes 
will bleed dry.)

>     * Method docs have examples
>     * No spelling errors (borrowing Pod::Spell)

What David said.

Also consider the various styles of method documenting.  I don't like 
the '=item method', but it happens.  I really don't like '=item 
method(parameters)', but again.  There better be some way to 
per-project declare this policy because anything besides "=head2 
method\n" is an error in my codebase.

The spelling thing could maybe be helped via C.  Would be nice 
to know that you didn't accidentally type some_metod_name when you 
wanted some_method_name.  Possibly use C to 
quality external refs.

Of course, "http://example.com";, acronyms, "Ingy" and similar items 
imply that a high-quality and sufficiently-hookable spellchecker are 
needed.  AFAIK, that doesn't exist.

>     * Module names are links

See 'See the "L documentation." may become "See the the perlpod 
manpage documentation."'  Too many links don't do that correctly 
already.  Thus, requiring links might be just making more trouble.

--Eric
-- 
Consumers want choice, consumers want openness.
--Rob Glaser
---
http://scratchcomputing.com
---

Re: Pod::Critic?

[Andy Lester]

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

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

Re: Pod::Critic?

[David Cantrell]

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

Re: Pod::Critic?

[jerry gay]

On 6/6/07, Ian Malpass <[EMAIL PROTECTED]> 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


this would be a help to the parrot project. we have coding standards
and have used perl::critic to good effect. we've also been working on
documentation standards, and a flexible and configurable tool that
makes it easy to enforce those standards would be most welcome.

i can think of a number of policies that we would like to enforce, and
i would be happy to provide them (and get them working) if this
project takes off.
~jerry

Pod::Critic?

[Ian Malpass]

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

Re: use_ok and %INC

[A. Pagaltzis]

* Smylers <[EMAIL PROTECTED]> [2007-06-06 13:25]:
> How about instead having use_ok simply removing the %INC entry
> if it's found, so that it can be used safely in exactly this
> situation?
> 
> Would doing that silently obscure any genuine bugs?

It would cause subroutine redefinition warnings and possibly
duplicate resource initialisation and other such badness if the
module really *was* loaded previously. Bad idea.

I think what we really want is to add `use_fails`, which *would*
be able to safely wipe the `%INC` entry after failure, because by
its very meaning, that test function can make an assumption that
is otherwise unsafe.

But both it and `use_ok` should warn if they find the key already
in `%INC`.

Although, as I wrote in comment at Ovid’s, it is `require` in
Perl itself that should really wipe the key whenever a) loading
fails and b) the key was not already there. Who knows if it’s
feasible to change that semantic at this late point, though.

Regards,
-- 
Aristotle Pagaltzis // 

Re: use_ok and %INC

[Smylers]

Ovid writes:

>   http://use.perl.org/~Ovid/journal/33441
> 
> In this case, I think either use_ok() should fail (which might break
> some test suites since its behavior has changed), or that it should
> issue a warning if $module is found in %INC.

How about instead having use_ok simply removing the %INC entry if it's
found, so that it can be used safely in exactly this situation?

Would doing that silently obscure any genuine bugs?

Smylers

use_ok and %INC

[Ovid]

In relation to this bug:

  http://use.perl.org/~Ovid/journal/33441

I had use_ok('Some::Module', @import_list) appear to succeed, even though it 
had not.  The imports weren't imported and that's because I had a previous 
failure with:

  eval 'use Some::Module';
  ok $@ ...

That put 'Some/Module.pm' in the %INC hash, preventing it from being reloaded 
with use_ok().

In this case, I think either use_ok() should fail (which might break some test 
suites since its behavior has changed), or that it should issue a warning if 
$module is found in %INC.

Does this sound reasonable?

Cheers,
Ovid
-- 
Buy the book -- http://www.oreilly.com/catalog/perlhks/
Perl and CGI -- http://users.easystreet.com/ovid/cgi_course/

Re: Kwalitee and "other dists requiring" report

[Thomas Klausner]

Hi!

On Tue, Jun 05, 2007 at 12:31:34PM -0500, Ian Malpass wrote:
> Would it be easy and/or interesting to add the kwalitee of the 
> distributions listed in the "other dists requiring X" section of the 
> CPANTS report?

That should be fairly easy to do.

I think I'll have some time this weekend/early next week to do some long 
outstanding CPANTS updates...

-- 
#!/usr/bin/perl  http://domm.plix.at
for(ref bless{},just'another'perl'hacker){s-:+-$"-g&&print$_.$/}