util/doc-nit-check.pl

   1 #! /usr/bin/env perl
   2 # Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
   3 #
   4 # Licensed under the OpenSSL license (the "License").  You may not use
   5 # this file except in compliance with the License.  You can obtain a copy
   6 # in the file LICENSE in the source distribution or at
   7 # https://www.openssl.org/source/license.html
   8
   9
  10 require 5.10.0;
  11 use warnings;
  12 use strict;
  13 use Pod::Checker;
  14 use File::Find;
  15 use File::Basename;
  16
  17 my $temp = '/tmp/docnits.txt';
  18 my $OUT;
  19
  20 my %mandatory_sections =
  21     ( '*'    => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ],
  22       1      => [ 'SYNOPSIS', '(COMMAND\s+)?OPTIONS' ],
  23       3      => [ 'SYNOPSIS', 'RETURN\s+VALUES' ],
  24       5      => [ ],
  25       7      => [ ] );
  26 my %default_sections =
  27     ( apps   => 1,
  28       crypto => 3,
  29       ssl    => 3 );
  30
  31 sub check()
  32 {
  33     my $filename = shift;
  34     my $dirname = basename(dirname($filename));
  35     my $contents = '';
  36     {
  37         local $/ = undef;
  38         open POD, $filename or die "Couldn't open $filename, $!";
  39         $contents = <POD>;
  40         close POD;
  41     }
  42     print $OUT "$filename doesn't start with =pod\n"
  43         if $contents !~ /^=pod/;
  44     print $OUT "$filename doesn't end with =cut\n"
  45         if $contents !~ /=cut\n$/;
  46     print $OUT "$filename more than one cut line.\n"
  47         if $contents =~ /=cut.*=cut/ms;
  48     print $OUT "$filename missing copyright\n"
  49         if $contents !~ /Copyright .* The OpenSSL Project Authors/;
  50     print $OUT "$filename copyright not last\n"
  51         if $contents =~ /head1 COPYRIGHT.*=head/ms;
  52     print $OUT "$filename head2 in All uppercase\n"
  53         if $contents =~ /head2.*[A-Z ]+\n/;
  54
  55     my $section = $default_sections{$dirname};
  56     if ($contents =~ /^=for\s+comment\s+openssl_manual_section:\s*(\d+)\s*$/m) {
  57         $section = $1;
  58     }
  59
  60     foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) {
  61         print $OUT "$filename doesn't have a head1 section matching $_\n"
  62             if $contents !~ /^=head1\s+${_}\s*$/m;
  63     }
  64
  65     podchecker($filename, $OUT);
  66 }
  67
  68 open $OUT, '>', $temp
  69     or die "Can't open $temp, $!";
  70 foreach (@ARGV ? @ARGV : glob('*/*.pod')) {
  71     &check($_);
  72 }
  73 close $OUT;
  74
  75 my $count = 0;
  76 open $OUT, '<', $temp
  77     or die "Can't read $temp, $!";
  78 while ( <$OUT> ) {
  79     next if /\(section\) in.*deprecated/;
  80     $count++;
  81     print;
  82 }
  83 close $OUT;
  84 unlink $temp || warn "Can't remove $temp, $!";
  85
  86 exit $count;