path: root/util/find-doc-nits

#! /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, s