t/codingstd/pod_description.t

   1 #! perl
   2 # Copyright (C) 2001-2010, Parrot Foundation.
   3 # $Id$
   4
   5 use strict;
   6 use warnings;
   7 use Carp;
   8 use Test::More;
   9 use lib qw( lib );
  10 BEGIN {
  11     eval 'use Parrot::Test::Pod';
  12     if ($@) {
  13         plan skip_all => 'Prerequisites for Parrot::Test::Pod not satisfied';
  14         exit;
  15     }
  16     eval 'use Parrot::Test::Pod::Utils qw(
  17         file_pod_ok
  18         empty_description
  19     )';
  20     if ($@) {
  21         plan skip_all =>
  22             'Prerequisites for Parrot::Test::Pod::Utils not satisfied';
  23         exit;
  24     }
  25 }
  26
  27 plan tests => 2;
  28
  29 my $self = Parrot::Test::Pod->new( {
  30     argv => [ @ARGV ],
  31 } );
  32 ok( defined $self, "Parrot::Test::Pod returned defined value" );
  33
  34 my $need_testing_ref = $self->identify_files_for_POD_testing( {
  35     second_analysis => 'oreilly_summary_malformed',
  36 } );
  37
  38 my @empty_description;
  39
  40 foreach my $file ( @{ $need_testing_ref } ) {
  41     # check DESCRIPTION section on valid POD files
  42     if ( file_pod_ok($file) and empty_description($file) ) {
  43         push @empty_description, $file;
  44     }
  45 }
  46
  47 my $empty_description_files = join( "\n", sort @empty_description);
  48 my $nempty_description      = scalar( @empty_description );
  49
  50 TODO: {
  51     local $TODO = 'POD requirements in flux: TT #292';
  52
  53 is(
  54     $empty_description_files,
  55     q{},
  56     'All Pod files have non-empty DESCRIPTION sections'
  57 );
  58 }
  59
  60 diag("\nFound $nempty_description files without DESCRIPTION sections.\n")
  61     if $nempty_description;
  62
  63 #################### SUBROUTINES ####################
  64
  65 =head1 NAME
  66
  67 t/codingstd/pod_description.t - Identify files lacking 'DESCRIPTION' in POD
  68
  69 =head1 SYNOPSIS
  70
  71     # test all files
  72     % prove t/codingstd/pod_description.t
  73
  74     # test specific files
  75     % perl t/codingstd/pod_description.t perl_module.pm perl_file.pl
  76
  77 =head1 DESCRIPTION
  78
  79 Tests the Pod syntax for all files listed in F<MANIFEST> and
  80 F<MANIFEST.generated> that appear to contain Pod markup. If any files
  81 contain with valid POD markup lack C<DESCRIPTION> sections, list them.
  82
  83 =cut
  84
  85 # Local Variables:
  86 #   mode: cperl
  87 #   cperl-indent-level: 4
  88 #   fill-column: 100
  89 # End:
  90 # vim: expandtab shiftwidth=4: