t/doc/pod.t

   1 #! perl
   2 # Copyright (C) 2001-2005, The Perl Foundation.
   3 # $Id$
   4
   5 =head1 NAME
   6
   7 t/doc/pod.t - Pod document syntax tests
   8
   9 =head1 SYNOPSIS
  10
  11     # test all files
  12     % prove t/doc/pod.t
  13
  14     # test specific files
  15     % perl t/doc/pod.t perl_module.pm perl_file.pl
  16
  17 =head1 DESCRIPTION
  18
  19 Tests the Pod syntax for all files listed in F<MANIFEST> and
  20 F<MANIFEST.generated> that appear to contain Pod markup. If any files
  21 contain invalid POD markup, they are reported in the test output.
  22 Use C<podchecker> to ferret out individual issues.
  23
  24 =cut
  25
  26 use strict;
  27 use warnings;
  28
  29 use lib qw( . lib ../lib ../../lib );
  30
  31 use Test::More;
  32 use Parrot::Config;
  33 use ExtUtils::Manifest qw(maniread);
  34
  35 use vars qw(@failed_syntax @empty_description);
  36
  37 BEGIN {
  38     eval 'use Pod::Find';
  39     if ($@) {
  40         plan skip_all => 'Pod::Find not installed';
  41         exit;
  42     }
  43     eval 'use Pod::Simple';
  44     if ($@) {
  45         plan skip_all => 'Pod::Simple not installed';
  46         exit;
  47     }
  48 }
  49
  50 plan tests => 2;
  51
  52 # RT#44437 this should really be using src_dir instead of build_dir but it
  53 # does not exist (yet)
  54 my $build_dir    = $PConfig{build_dir};
  55 my $manifest     = maniread("$build_dir/MANIFEST");
  56 my $manifest_gen = maniread("$build_dir/MANIFEST.generated");
  57
  58 # if we have files passed in at the command line, use them
  59 my @files;
  60 if (@ARGV) {
  61     @files = @ARGV;
  62 }
  63 else {
  64     diag "finding files with POD, this may take a minute.";
  65     @files = ( keys(%$manifest), keys(%$manifest_gen) );
  66 }
  67
  68 foreach my $file (@files) {
  69     $file = "$build_dir/$file";
  70
  71     # skip missing MANIFEST.generated files ( -e )
  72     # skip binary files (including .pbc files) ( -B )
  73     # skip files that pass the -e test because they resolve the .exe variant
  74     next unless -T $file;
  75
  76     # Skip the book, because it uses extended O'Reilly-specific POD
  77     next if $file =~ m{docs/book/};
  78
  79     # skip files without POD
  80     next unless Pod::Find::contains_pod( $file, 0 );
  81
  82     # skip POD generating scripts
  83     next if $file =~ m/ops_summary\.pl/;
  84
  85     # skip file which includes malformed POD for other testing purposes
  86     next if $file =~ m{t/tools/dev/searchops/samples\.pm};
  87
  88     # skip files with valid POD
  89     if (file_pod_ok($file)) {
  90
  91         #check DESCRIPTION section on valid POD files
  92         push @empty_description, $file if empty_description($file);
  93
  94     }
  95     else {
  96
  97         # report whatever is not skipped
  98         push @failed_syntax, $file;
  99     }
 100 }
 101
 102 my $bad_syntax_files = join( "\n", @failed_syntax );
 103 my $empty_description_files = join( "\n", @empty_description);
 104 my $nempty_description = scalar( @empty_description );
 105
 106 is( $bad_syntax_files, q{}, 'Pod syntax correct' );    # only ok if everything passed
 107
 108 TODO: {
 109     local $TODO = "not quite done yet";
 110     is( $empty_description_files, q{}, 'All Pod files have non-empty DESCRIPTION sections' );
 111 }
 112
 113 diag("You should use podchecker to check the failed files.\n")
 114     if $bad_syntax_files;
 115
 116 diag("Found $nempty_description files without DESCRIPTION sections.\n")
 117     if $nempty_description;
 118
 119 # Pulled from Test::Pod
 120 sub file_pod_ok {
 121     my $file    = shift;
 122     my $checker = Pod::Simple->new;
 123
 124     $checker->output_string( \my $trash );      # Ignore any output
 125     $checker->parse_file($file);
 126
 127     return !$checker->any_errata_seen;
 128 }
 129
 130 sub empty_description {
 131     my $file = shift;
 132
 133     use Pod::Simple::PullParser;
 134     my $parser = Pod::Simple::PullParser->new;
 135     $parser->set_source( $file );
 136     my $description = $parser->get_description;
 137
 138     if ( $description =~ m{^\s*$}m ) {
 139         return 1;
 140     }
 141
 142     return 0;
 143 }
 144
 145 # Local Variables:
 146 #   mode: cperl
 147 #   cperl-indent-level: 4
 148 #   fill-column: 100
 149 # End:
 150 # vim: expandtab shiftwidth=4: