I'm pleased to announce the first alpha of Pod::Coverage. It's a
simple tool for determining if your module is covered by it's internal
pod.
It's available here, and if I didn't fluff it, the README file is attached
http://unixbeard.net/~richardc/lab/Pod-Coverage/Pod-Coverage-0.01_02.tar.gz
Caveats, this isn't heading to CPAN today at the testsuite is far from
comprehensive, and I'd like some feedback before I release it. That
and I was due to meet people at the pub an hour ago.
Testcases that fail would be greatly appreciated so I know what to
shoot at next.
--
Richard Clamp <[EMAIL PROTECTED]>
NAME
Pod::Coverage - Checks if the documentation of a module is comprehensive
SYNOPSIS
# all in one invocation
use Pod::Coverage package => 'Fishy';
# straight OO
use Pod::Coverage;
my $pc = new Pod::Coverage package => 'Pod::Coverage';
print "We rock!" if $pc->coverage == 1;
DESCRIPTION
Developers hate writing documentation. They'd hate it even more if their
computer tattled on them, but maybe they'll be even more thankful in the
long run.
This module provides a mechanism for determining if the pod for a given
module is comprehensive.
It expects to find either a =head2 or an =item block documenting a
subroutine.
Consider: # an imaginary Foo.pm package Foo;
=item foo
The foo sub
= cut
sub foo {}
sub bar {}
1;
__END__
In this example Foo::foo is covered, but Foo::bar is not, so the Foo
package is only 50% (0.5) covered
Methods
Pod::Coverage->new(package => $package)
Creates a new Pod::Coverage object. Takes one parameter, the name of
the package to analyse.
$object->coverage
Gives the coverage as a value in the range 0 to 1
BUGS
Due to the method used to identify documented subroutines
"Pod::Coverage" may completely miss your house style and declare your
code undocumented. Patches welcome.
Also the code currently only deals with packages in their own .pm files,
this will be adressed with the next release.
TODO
Examine globals and explicitly exported symbols
Determine if ancestor packages declare things left undocumented
Widen the rules for identifying documentation (must check what
perlmodstyle recommends and obey that)
HISTORY
Version 0.01
As #london.pm invaded Brighton, people taked about documentation
standards. mstevens scribbled something down, richardc coded it, the
rest is ponies.
AUTHORS
Richard Clamp <[EMAIL PROTECTED]>
Michael Stevens <[EMAIL PROTECTED]>
Copyright (c) 2001 Richard Clamp, Micheal Stevens. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
