t/codingstd/c_function_docs.t

   1 #! perl
   2 # Copyright (C) 2006-2010, Parrot Foundation.
   3 # $Id$
   4
   5 use strict;
   6 use warnings;
   7
   8 use lib qw( . lib ../lib ../../lib );
   9 use Test::More;
  10 use Parrot::Config qw(%PConfig);
  11 use Parrot::Distribution;
  12 use Parrot::Headerizer;
  13
  14 =head1 NAME
  15
  16 t/codingstd/c_function_docs.t - checks for missing function documentation
  17
  18 =head1 SYNOPSIS
  19
  20     # test all files
  21     % prove t/codingstd/c_function_docs.t
  22
  23     # test specific files
  24     % perl t/codingstd/c_function_docs.t src/foo.c include/parrot/bar.h
  25
  26 =head1 DESCRIPTION
  27
  28 Checks that all C language source files have documentation for each function
  29 declared.
  30
  31 =cut
  32
  33 my $DIST = Parrot::Distribution->new;
  34 my $headerizer = Parrot::Headerizer->new;
  35
  36 # can not handle .ops or .pmc files yet
  37 my @files = grep {/\.(c|h)$/ } @ARGV ? @ARGV :
  38     map {s/^$PConfig{build_dir}\///; $_} map {s/\\/\//g; $_} map {$_->path} $DIST->get_c_language_files();
  39
  40 plan tests => scalar @files;
  41
  42 my %todos;
  43 while (<DATA>) {
  44     next if /^#/;
  45     next if /^\s*$/;
  46     chomp;
  47     $todos{$_} = 1;
  48 }
  49
  50 foreach my $path (@files) {
  51
  52     my $buf = $DIST->slurp($path);
  53     my @missing_docs;
  54
  55     my @function_decls = $headerizer->extract_function_declarations($buf);
  56
  57     for my $function_decl (@function_decls) {
  58
  59         my $escaped_decl = $headerizer->generate_documentation_signature($function_decl);
  60
  61         my $missing = '';
  62         if ( $buf =~ m/^\Q$escaped_decl\E$(.*?)^=cut/sm ) {
  63             my $docs = $1;
  64             $docs =~ s/\s//g;
  65             if ($docs eq '') {
  66                 $missing = 'boilerplate only';
  67             }
  68             # else:  docs!
  69         }
  70         else {
  71             $missing = 'missing';
  72         }
  73         if ($missing) {
  74             if ($missing eq 'boilerplate only') {
  75                 push @missing_docs, "$path ($missing)\nIn:\n$escaped_decl\n";
  76             }
  77             else {
  78                 push @missing_docs, "$path ($missing)\n$function_decl\nWant:\n$escaped_decl\n";
  79             }
  80         }
  81     }
  82
  83     TODO: {
  84         local $TODO = 'Missing function docs' if $todos{$path};
  85
  86     ok ( ! @missing_docs, $path)
  87         or diag( @missing_docs
  88             . " function(s) lacking documentation:\n"
  89             . join ("\n", @missing_docs, "\n"));
  90     }
  91 }
  92
  93 __DATA__
  94
  95 # Local Variables:
  96 #   mode: cperl
  97 #   cperl-indent-level: 4
  98 #   fill-column: 100
  99 # End:
 100 # vim: expandtab shiftwidth=4: