Fix missing HISTORY doc entries

Also add a check to find-doc-nits for HISTORY sections.

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/26188)

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;