Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
tree: a6515dacf0
Fetching contributors…

Cannot retrieve contributors at this time

executable file 174 lines (119 sloc) 4.532 kB
#!/usr/bin/perl
#
=head1 NAME
pod.pl - check the POD documentation syntax in modules and scripts
=head1 SYNOPSIS
B<pod.pl> [B<-d|--dir> path ] [B<-v|--verbose>] B<-b|--blankline>
[B<-?|-h|--help>]
=head1 DESCRIPTION
Checks Plain Old Documentation (POD) with highest possible stringency
in every bioperl module and script in CVS modules 'core' and 'run'.
Amounts to same as running
podchecker -warnings -warnings
on every file.
=head2 Results
The results are written into file '/tmp/bioperl_pod_check' and
displayed after the run. The output is filtered not to show
confirmations of correct syntax. The result file is not removed.
The aim is to have as few warnings, and no errors, as possible. Links
to web URLs give a warning but that seems to be spurious, so they are
filtered out. Currently there are a few cases of "multiple occurrence
of link target" in several modules which are harmless.
=head1 SEE ALSO
L<podchecker>, L<Pod::Checker>
=cut
use File::Find;
use Pod::Checker;
use Getopt::Long;
use strict;
sub podcheck;
sub blankline;
#
## Directories to check
#
my @dirs = qw( ../Bio/ ../scripts . );
# command line options
my ($verbose, $blankline, $dir, $help) = (0, undef, undef, undef);
GetOptions(
'v|verbose' => \$verbose,
'dir:s' => \$dir,
'blankline' => \$blankline,
'h|help|?' => sub{ exec('perldoc',$0); exit(0) }
);
# setup
my $tmpfile = '/tmp/bioperl_pod_check';
our %POD_CHECKER_OPTIONS = ( '-warnings' => 2 );
our %FIND_OPTIONS = ( wanted => \&podcheck, no_chdir => 1 );
# run
open (F, ">$tmpfile") || die "can't open file $tmpfile: $!";
$FIND_OPTIONS{wanted} = \&blankline if $blankline;
if ($dir) {
find \%FIND_OPTIONS, $dir;
} else {
find \%FIND_OPTIONS, @dirs;
}
close F;
open (F, "grep -v OK $tmpfile|") || die "can't open file $tmpfile: $!";
while (<F>) { print unless /http/ and /non-escaped/ }
# this is where the action is
sub podcheck {
return unless /\.PLS$/ or /\.p[ml]$/ ;
return unless -e $_;
print "$_\n" if $verbose;
my $checker = Pod::Checker->new( %POD_CHECKER_OPTIONS );
$checker->parse_from_file($_, \*F);
print "$_\tno POD\n" if $checker->num_errors() < 0;
}
=head1 OPTIONS
=over 3
=item B<-d | --dir> path
Overides the default directories to check by one directory 'path' and
all its subdirectories.
=item B<-b | --blankline>
Checks POD command paragraphs (lines starting with '=' character) for
preceding nonblank lines. These lines are printed out with '++'.
Also, if verbose is turned on, it will report on lines whitespace
characters which prevent paragrafs to be recognised by older POD
parsers (marked with '+'). Modern perlpod parsers (5.6.0 and later, I
suppose) allow for whitespace lines surrounding command lines, but
since bioperl still supports older versions, these lines should be
cleaned to contain only '\n' and no space or tab characters.
See: L<perlpodspec>
=cut
sub blankline {
return unless /\.PLS$/ or /\.p[ml]$/ ;
return unless -e $_;
my $file = $_;
open (F, $_) or warn "can't open file $_: $!" && return;
local $/="";
while (<F>) {
print "$file: +|$1|\n" if /[ \t]\n(=[a-z][^\n]+$)/m and $verbose;
print "$file: ++|$1|\n" if /\w\n(=[a-z][^\n]+$)/m and $verbose;
print "$file:|$1|+\n" if /(^=[a-z][^\n]+)\n[\t ]/m;
#print "$file:|$1|++\n" if /(^=[^\n]+)\n\w/m;
}
close F;
}
__END__
=item B<-v | --verbose>
Show the progress through files during the POD checking.
=item B<-? | -h | --help>
This help text.
=back
=head1 FEEDBACK
=head2 Mailing Lists
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to
the Bioperl mailing list. Your participation is much appreciated.
bioperl-l@bioperl.org - General discussion
http://bioperl.org/wiki/Mailing_lists - About the mailing lists
=head2 Reporting Bugs
Report bugs to the Bioperl bug tracking system to help us keep track
of the bugs and their resolution. Bug reports can be submitted via the
web:
https://redmine.open-bio.org/projects/bioperl/
=head1 AUTHOR - Heikki Lehvaslaiho
Email heikki-at-bioperl-dot-org
=cut
# find . -name '*.pm' -print | xargs perl -e '$/=""; while (<>) {$n = $1 if /^package\s+([\w:]+)/; print "$n:|$1|" if /(\s\s^=[^\n]+$)/m ; }' ;
# find . -name '*.pm' -print | xargs perl -e '$/=""; while (<>) {$n = $1 if /^package\s+([\w:]+)/; print "$n:|$1|\n" if /(^=[^\n]+\n[\t ])/m ; }' ;
Jump to Line
Something went wrong with that request. Please try again.