#! /usr/bin/env perl
# Copyright 2002-2021 The OpenSSL Project Authors. All Rights Reserved.
#
# Licensed under the Apache License 2.0 (the "License"). You may not use
# this file except in compliance with the License. You can obtain a copy
# in the file LICENSE in the source distribution or at
# https://www.openssl.org/source/license.html
require 5.10.0;
use warnings;
use strict;
use Carp qw(:DEFAULT cluck);
use Pod::Checker;
use File::Find;
use File::Basename;
use File::Spec::Functions;
use Getopt::Std;
use FindBin;
use lib "$FindBin::Bin/perl";
use OpenSSL::Util::Pod;
use lib '.';
use configdata;
# Set to 1 for debug output
my $debug = 0;
# Options.
our($opt_d);
our($opt_e);
our($opt_s);
our($opt_o);
our($opt_h);
our($opt_l);
our($opt_m);
our($opt_n);
our($opt_p);
our($opt_u);
our($opt_v);
our($opt_c);
# Print usage message and exit.
sub help {
print <<EOF;
Find small errors (nits) in documentation. Options:
-c List undocumented commands, undocumented options and unimplemented options.
-d Detailed list of undocumented (implies -u)
-e Detailed list of new undocumented (implies -v)
-h Print this help message
-l Print bogus links
-m Name(s) of manuals to focus on. Default: man1,man3,man5,man7
-n Print nits in POD pages
-o Causes -e/-v to count symbols added since 1.1.1 as new (implies -v)
-u Count undocumented functions
-v Count new undocumented functions
EOF
exit;
}
getopts('cdehlm:nouv');
help() if $opt_h;
$opt_u = 1 if $opt_d;
$opt_v = 1 if $opt_o || $opt_e;
die "Cannot use both -u and -v"
if $opt_u && $opt_v;
die "Cannot use both -d and -e"
if $opt_d && $opt_e;
# We only need to check c, l, n, u and v.
# Options d, e, o imply one of the above.
die "Need one of -[cdehlnouv] flags.\n"
unless $opt_c or $opt_l or $opt_n or $opt_u or $opt_v;
my $temp = '/tmp/docnits.txt';
my $OUT;
my $status = 0;
$opt_m = "man1,man3,man5,man7" unless $opt_m;
die "Argument of -m option may contain only man1, man3, man5, and/or man7"
unless $opt_m =~ /^(man[1357][, ]?)*$/;
my @sections = ( split /[, ]/, $opt_m );
my %mandatory_sections = (
'*' => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ],
1 => [ 'SYNOPSIS', 'OPTIONS' ],
3 => [ 'SYNOPSIS', 'RETURN VALUES' ],
5 => [ ],
7 => [ ]
);
# Symbols that we ignored.
# They are reserved macros that we currently don't document
my $ignored = qr/(?| ^i2d_
| ^d2i_
| ^DEPRECATEDIN
| ^OSSL_DEPRECATED
| \Q_fnsig(3)\E$
| ^IMPLEMENT_
| ^_?DECLARE_
| ^sk_
| ^SKM_DEFINE_STACK_OF_INTERNAL
| ^lh_
| ^DEFINE_LHASH_OF_INTERNAL
)/x;
# A common regexp for C symbol names
my $C_symbol = qr/\b[[:alpha:]][_[:alnum:]]*\b/;
# Collect all POD files, both internal and public, and regardless of location
# We collect them in a hash table with each file being a key, so we can attach
# tags to them. For example, internal docs will have the word "internal"
# attached to them.
my %files