#! /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_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 and 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
-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('cdehlnouv');
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;
my @sections = ( 'man1', 'man3', 'man5', 'man7' );
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 = ();
# We collect files names on the fly, on known tag basis
my %collected_tags = ();
# We cache results based on tags
my %collected_results = ();
# files OPTIONS
#
# Example:
#
# files(TAGS => 'manual');
# files(TAGS => [ 'manual', 'man1' ]);
#
# This function returns an array of files corresponding to a set of tags
# given with the options "TAGS". The value of this option can be a single
# word, or an array of several words, which work as inclusive or exclusive
# selectors. Inclusive selectors are used to add one more set of files to
# the returned array, while exclusive selectors limit the set of files added
# to the array. The recognised tag values are:
#
# 'public_manual' - inclusive selector, adds public manuals to the
# returned array of files.
# 'internal_manual' - incl