diff options
Diffstat (limited to 'util')
| -rwxr-xr-x | util/find-doc-nits | 46 |
1 files changed, 45 insertions, 1 deletions
diff --git a/util/find-doc-nits b/util/find-doc-nits index 7d1cdb59b1..8a5c26fb61 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -41,6 +41,7 @@ our($opt_p); our($opt_u); our($opt_v); our($opt_c); +our($opt_i); # Print usage message and exit. sub help { @@ -54,13 +55,14 @@ Find small errors (nits) in documentation. Options: -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) + -i Checks for history entries available for symbols added since 3.0.0 as new -u Count undocumented functions -v Count new undocumented functions EOF exit; } -getopts('cdehlm:nouv'); +getopts('cdehlm:noiuv'); help() if $opt_h; $opt_u = 1 if $opt_d; @@ -433,6 +435,29 @@ sub check_section_location { if $contents =~ /=head1 $before.*=head1 $section/ms; } +# Check if HISTORY section is present and functionname ($2) is present in it +# or a generic "(f)unction* added" term hints at several new functions in +# the documentation (yes, this is an approximation only but it works :) +sub find_functionname_in_history_section { + my $contents = shift; + my $functionname = shift; + my (undef, $rest) = split('=head1 HISTORY\s*', $contents); + + if (not $rest) { + # No HISTORY section is a clear error now + return 0; + } + else { + my ($histsect, undef) = split('=head1 COPYRIGHT\s*', $rest); + if (index($histsect, $functionname) == -1) { + # OK, functionname is not in HISTORY section... + # last try: Check for presence of "*unction*added*" + return 0 if (not $histsect =~ /unction.*added.*/g); + } + } + return 1; +} + # Check if a =head1 is duplicated, or a =headX is duplicated within a # =head1. Treats =head2 =head3 as equivalent -- it doesn't reset the head3 # sets if it finds a =head2 -- but that is good enough for now. Also check @@ -842,6 +867,8 @@ my %name_map = (); # Any of these values except 'public' may be prefixed with 'missing_' # to indicate that they are known to be missing. my %state; +# history contains the same as state above for entries with version info != 3_0_0 +my %history; # %missing is affected by loading util/missing*.txt. Values may be one of: # 'crypto' : belongs in libcrypto (loaded from libcrypto.num) # 'ssl' : belongs in libssl (loaded from libssl.num) @@ -862,6 +889,12 @@ sub loadnum ($;$) { next if /^#/; next if /\bNOEXIST\b/; my @fields = split(); + if ($type && ($type eq "crypto" || $type eq "ssl")) { + # 3rd field is version + if (not $fields[2] eq "3_0_0") { + $history{$fields[0].'(3)'} = $type.$fields[2]; + } + } die "Malformed line $. in $file: $_" if scalar @fields != 2 && scalar @fields != 4; $state{$fields[0].'(3)'} = $type // 'internal'; @@ -952,6 +985,8 @@ sub printem ($) { my $count = 0; foreach my $func ( grep { $state{$_} eq $type } sort keys %state ) { + err("$type:", "function $func not in any history section") + if ($opt_i && defined $history{$func}); next if defined $name_map{$func} || defined $missing{$func}; @@ -984,6 +1019,15 @@ sub collectnames { my $name_sec = "$name($section)"; if ( !defined $name_map{$name_sec} ) { $name_map{$name_sec} = $filename; + if ($history{$name_sec}) { + my $funcname = $name_sec; + my $contents = $podinfo{contents}; + $funcname =~ s/\(.*//; + if (find_functionname_in_history_section($contents, $funcname)) { + # mark this function as found/no longer of interest + $history{$name_sec} = undef; + } + } $state{$name_sec} //= ( $filename =~ /\/internal\// ? 'internal' : 'public' ) if $is_generic; |