This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
https://perl5.git.perl.org / perl5.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Merge the sfio removal to blead.
[perl5.git] / autodoc.pl
diff --git a/autodoc.pl b/autodoc.pl
index 2e5217e..bff2094 100644 (file)
--- a/autodoc.pl
+++ b/autodoc.pl
@@ -13,11 +13,25 @@
 # Has an optional arg, which is the directory to chdir to before reading
 # MANIFEST and *.[ch].
 #
 # Has an optional arg, which is the directory to chdir to before reading
 # MANIFEST and *.[ch].
 #
-# This script is normally invoked as part of 'make all', but is also
-# called from from regen.pl.
+# This script is invoked as part of 'make all'
+#
+# '=head1' are the only headings looked for.  If the next line after the
+# heading begins with a word character, it is considered to be the first line
+# of documentation that applies to the heading itself.  That is, it is output
+# immediately after the heading, before the first function, and not indented.
+# The next input line that is a pod directive terminates this heading-level
+# documentation.
 
 use strict;
 
 
 use strict;
 
+if (@ARGV) {
+    my $workdir = shift;
+    chdir $workdir
+        or die "Couldn't chdir to '$workdir': $!";
+}
+require 'regen/regen_lib.pl';
+require 'regen/embed_lib.pl';
+
 #
 # See database of global and static function prototypes in embed.fnc
 # This is used to generate prototype headers under various configurations,
 #
 # See database of global and static function prototypes in embed.fnc
 # This is used to generate prototype headers under various configurations,
@@ -39,7 +53,7 @@ my $curheader = "Unknown section";
 
 sub autodoc ($$) { # parse a file and extract documentation info
     my($fh,$file) = @_;
 
 sub autodoc ($$) { # parse a file and extract documentation info
     my($fh,$file) = @_;
-    my($in, $doc, $line);
+    my($in, $doc, $line, $header_doc);
 FUNC:
     while (defined($in = <$fh>)) {
        if ($in =~ /^#\s*define\s+([A-Za-z_][A-Za-z_0-9]+)\(/ &&
 FUNC:
     while (defined($in = <$fh>)) {
        if ($in =~ /^#\s*define\s+([A-Za-z_][A-Za-z_0-9]+)\(/ &&
@@ -49,6 +63,35 @@ FUNC:
        }
         if ($in=~ /^=head1 (.*)/) {
             $curheader = $1;
        }
         if ($in=~ /^=head1 (.*)/) {
             $curheader = $1;
+
+            # If the next line begins with a word char, then is the start of
+            # heading-level documentation.
+           if (defined($doc = <$fh>)) {
+                if ($doc !~ /^\w/) {
+                    $in = $doc;
+                    redo FUNC;
+                }
+                $header_doc = $doc;
+                $line++;
+
+                # Continue getting the heading-level documentation until read
+                # in any pod directive (or as a fail-safe, find a closing
+                # comment to this pod in a C language file
+HDR_DOC:
+                while (defined($doc = <$fh>)) {
+                    if ($doc =~ /^=\w/) {
+                        $in = $doc;
+                        redo FUNC;
+                    }
+                    $line++;
+
+                    if ($doc =~ m:^\s*\*/$:) {
+                        warn "=cut missing? $file:$line:$doc";;
+                        last HDR_DOC;
+                    }
+                    $header_doc .= $doc;
+                }
+            }
             next FUNC;
         }
        $line++;
             next FUNC;
         }
        $line++;
@@ -77,6 +120,7 @@ DOC:
            if ($docref and %$docref) {
                $embed_where = $docref->{flags} =~ /A/ ? 'api' : 'guts';
                $embed_may_change = $docref->{flags} =~ /M/;
            if ($docref and %$docref) {
                $embed_where = $docref->{flags} =~ /A/ ? 'api' : 'guts';
                $embed_may_change = $docref->{flags} =~ /M/;
+                $flags .= 'D' if $docref->{flags} =~ /D/;
            } else {
                $missing{$name} = $file;
            }
            } else {
                $missing{$name} = $file;
            }
@@ -111,6 +155,13 @@ DOC:
            $docs{$inline_where}{$curheader}{$name}
                = [$flags, $docs, $ret, $file, @args];
 
            $docs{$inline_where}{$curheader}{$name}
                = [$flags, $docs, $ret, $file, @args];
 
+            # Create a special entry with an empty-string name for the
+            # heading-level documentation.
+           if (defined $header_doc) {
+                $docs{$inline_where}{$curheader}{""} = $header_doc;
+                undef $header_doc;
+            }
+
            if (defined $doc) {
                if ($doc =~ /^=(?:for|head)/) {
                    $in = $doc;
            if (defined $doc) {
                if ($doc =~ /^=(?:for|head)/) {
                    $in = $doc;
@@ -128,8 +179,15 @@ sub docout ($$$) { # output the docs for one function
     my($flags, $docs, $ret, $file, @args) = @$docref;
     $name =~ s/\s*$//;
 
     my($flags, $docs, $ret, $file, @args) = @$docref;
     $name =~ s/\s*$//;
 
-    $docs .= "NOTE: this function is experimental and may change or be
-removed without notice.\n\n" if $flags =~ /x/;
+    if ($flags =~ /D/) {
+        $docs = "\n\nDEPRECATED!  It is planned to remove this function from a
+future release of Perl.  Do not use it for new code; remove it from
+existing code.\n\n$docs";
+    }
+    else {
+        $docs = "\n\nNOTE: this function is experimental and may change or be
+removed without notice.\n\n$docs" if $flags =~ /x/;
+    }
     $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n"
        if $flags =~ /p/;
     $docs .= "NOTE: this function must be explicitly called as Perl_$name with an aTHX_ parameter.\n\n"
     $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n"
        if $flags =~ /p/;
     $docs .= "NOTE: this function must be explicitly called as Perl_$name with an aTHX_ parameter.\n\n"
@@ -143,37 +201,76 @@ removed without notice.\n\n" if $flags =~ /x/;
        print $fh "\t\t$name;\n\n";
     } elsif ($flags =~ /n/) { # no args
        print $fh "\t$ret\t$name\n\n";
        print $fh "\t\t$name;\n\n";
     } elsif ($flags =~ /n/) { # no args
        print $fh "\t$ret\t$name\n\n";
-    } elsif ($flags =~ /o/) { # no #define foo Perl_foo
-        print $fh "\t$ret\tPerl_$name";
-        print $fh "(" . (@args ? "pTHX_ " : "pTHX");
-        print $fh join(", ", @args) . ")\n\n";
     } else { # full usage
     } else { # full usage
-       print $fh "\t$ret\t$name";
-       print $fh "(" . join(", ", @args) . ")";
-       print $fh "\n\n";
+       my $p            = $flags =~ /o/; # no #define foo Perl_foo
+       my $n            = "Perl_"x$p . $name;
+       my $large_ret    = length $ret > 7;
+       my $indent_size  = 7+8 # nroff: 7 under =head + 8 under =item
+                         +8+($large_ret ? 1 + length $ret : 8)
+                         +length($n) + 1;
+       my $indent;
+       print $fh "\t$ret" . ($large_ret ? ' ' : "\t") . "$n(";
+       my $long_args;
+       for (@args) {
+           if ($indent_size + 2 + length > 79) {
+               $long_args=1;
+               $indent_size -= length($n) - 3;
+               last;
+           }
+       }
+       my $args = '';
+       if ($p) {
+           $args = @args ? "pTHX_ " : "pTHX";
+           if ($long_args) { print $fh $args; $args = '' }
+       }
+       $long_args and print $fh "\n";
+       my $first = !$long_args;
+       while () {
+           if (!@args or
+                length $args
+                && $indent_size + 3 + length($args[0]) + length $args > 79
+           ) {
+               print $fh
+                 $first ? '' : (
+                   $indent //=
+                      "\t".($large_ret ? " " x (1+length $ret) : "\t")
+                     ." "x($long_args ? 4 : 1 + length $n)
+                 ),
+                 $args, (","x($args ne 'pTHX_ ') . "\n")x!!@args;
+               $args = $first = '';
+           }
+           @args or last;
+           $args .= ", "x!!(length $args && $args ne 'pTHX_ ')
+                  . shift @args;
+       }
+       if ($long_args) { print $fh "\n", substr $indent, 0, -4 }
+       print $fh ")\n\n";
     }
     print $fh "=for hackers\nFound in file $file\n\n";
 }
 
 sub output {
     my ($podname, $header, $dochash, $missing, $footer) = @_;
     }
     print $fh "=for hackers\nFound in file $file\n\n";
 }
 
 sub output {
     my ($podname, $header, $dochash, $missing, $footer) = @_;
-    my $filename = "pod/$podname.pod";
-    open my $fh, '>', $filename or die "Can't open $filename: $!";
-
-    print $fh <<"_EOH_", $header;
--*- buffer-read-only: t -*-
-
-!!!!!!!   DO NOT EDIT THIS FILE   !!!!!!!
-This file is built by $0 extracting documentation from the C source
-files.
+    my $fh = open_new("pod/$podname.pod", undef,
+                     {by => "$0 extracting documentation",
+                       from => 'the C source files'}, 1);
 
 
-_EOH_
+    print $fh $header;
 
     my $key;
     # case insensitive sort, with fallback for determinacy
     for $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$dochash) {
        my $section = $dochash->{$key}; 
 
     my $key;
     # case insensitive sort, with fallback for determinacy
     for $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$dochash) {
        my $section = $dochash->{$key}; 
-       print $fh "\n=head1 $key\n\n=over 8\n\n";
+       print $fh "\n=head1 $key\n\n";
+
+        # Output any heading-level documentation and delete so won't get in
+        # the way later
+        if (exists $section->{""}) {
+            print $fh $section->{""} . "\n";
+            delete $section->{""};
+        }
+       print $fh "=over 8\n\n";
+
        # Again, fallback for determinacy
        for my $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$section) {
            docout($fh, $key, $section->{$key});
        # Again, fallback for determinacy
        for my $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$section) {
            docout($fh, $key, $section->{$key});
@@ -183,12 +280,24 @@ _EOH_
 
     if (@$missing) {
         print $fh "\n=head1 Undocumented functions\n\n";
 
     if (@$missing) {
         print $fh "\n=head1 Undocumented functions\n\n";
-    print $fh <<'_EOB_';
-Some functions are currently undocumented; use at your own risk, as the
-interfaces are subject to change.  If you use one of these, do everyone a
-favor by creating documentation for it.  The acceptance of your patch will
-indicate that the interface is stable (unless it is explicitly marked
-otherwise).  The undocumented functions are:
+    print $fh $podname eq 'perlapi' ? <<'_EOB_' : <<'_EOB_';
+The following functions have been flagged as part of the public API,
+but are currently undocumented. Use them at your own risk, as the
+interfaces are subject to change.  Functions that are not listed in this
+document are not intended for public use, and should NOT be used under any
+circumstances.
+
+If you use one of the undocumented functions below, you may wish to consider
+creating and submitting documentation for it. If your patch is accepted, this
+will indicate that the interface is stable (unless it is explicitly marked
+otherwise).
+
+=over
+
+_EOB_
+The following functions are currently undocumented.  If you use one of
+them, you may wish to consider creating and submitting documentation for
+it.
 
 =over
 
 
 =over
 
@@ -198,41 +307,15 @@ _EOB_
     }
     print $fh "=back\n\n";
 }
     }
     print $fh "=back\n\n";
 }
+    print $fh $footer, "=cut\n";
 
 
-print $fh $footer, <<'_EOF_';
-=cut
-
- ex: set ro:
-_EOF_
-
-    close $fh or die "Can't close $filename: $!";
+    read_only_bottom_close_and_rename($fh);
 }
 
 }
 
-if (@ARGV) {
-    my $workdir = shift;
-    chdir $workdir
-        or die "Couldn't chdir to '$workdir': $!";
-}
-
-open IN, "embed.fnc" or die $!;
-
-while (<IN>) {
-    chomp;
-    next if /^:/;
-    while (s|\\\s*$||) {
-       $_ .= <IN>;
-       chomp;
-    }
-    s/\s+$//;
-    next if /^\s*(#|$)/;
-
-    my ($flags, $retval, $func, @args) = split /\s*\|\s*/, $_;
-
-    next unless $func;
-
-    s/\b(NN|NULLOK)\b\s+//g for @args;
-    $func =~ s/\t//g; # clean up fields from embed.pl
-    $retval =~ s/\t//;
+foreach (@{(setup_embed())[0]}) {
+    next if @$_ < 2;
+    my ($flags, $retval, $func, @args) = @$_;
+    s/\b(?:NN|NULLOK)\b\s+//g for @args;
 
     $funcflags{$func} = {
                         flags => $flags,
 
     $funcflags{$func} = {
                         flags => $flags,
@@ -241,21 +324,19 @@ while (<IN>) {
                        };
 }
 
                        };
 }
 
-my $file;
 # glob() picks up docs from extra .c or .h files that may be in unclean
 # development trees.
 # glob() picks up docs from extra .c or .h files that may be in unclean
 # development trees.
-my $MANIFEST = do {
-  local ($/, *FH);
-  open FH, "MANIFEST" or die "Can't open MANIFEST: $!";
-  <FH>;
-};
+open my $fh, '<', 'MANIFEST'
+    or die "Can't open MANIFEST: $!";
+while (my $line = <$fh>) {
+    next unless my ($file) = $line =~ /^(\S+\.[ch])\t/;
 
 
-for $file (($MANIFEST =~ /^(\S+\.c)\t/gm), ($MANIFEST =~ /^(\S+\.h)\t/gm)) {
     open F, "< $file" or die "Cannot open $file for docs: $!\n";
     $curheader = "Functions in file $file\n";
     autodoc(\*F,$file);
     close F or die "Error closing $file: $!\n";
 }
     open F, "< $file" or die "Cannot open $file for docs: $!\n";
     $curheader = "Functions in file $file\n";
     autodoc(\*F,$file);
     close F or die "Error closing $file: $!\n";
 }
+close $fh or die "Error whilst reading MANIFEST: $!";
 
 for (sort keys %funcflags) {
     next unless $funcflags{$_}{flags} =~ /d/;
 
 for (sort keys %funcflags) {
     next unless $funcflags{$_}{flags} =~ /d/;
@@ -274,7 +355,9 @@ foreach (sort keys %missing) {
 # walk table providing an array of components in each line to
 # subroutine, printing the result
 
 # walk table providing an array of components in each line to
 # subroutine, printing the result
 
-my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && !$docs{api}{$_}, keys %funcflags;
+# List of funcs in the public API that aren't also marked as experimental nor
+# deprecated.
+my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && $funcflags{$_}{flags} !~ /[MD]/ && !$docs{api}{$_}, keys %funcflags;
 output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<'_EOE_');
 =head1 NAME
 
 output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<'_EOE_');
 =head1 NAME
 
@@ -284,7 +367,7 @@ perlapi - autogenerated documentation for the perl public API
 X<Perl API> X<API> X<api>
 
 This file contains the documentation of the perl public API generated by
 X<Perl API> X<API> X<api>
 
 This file contains the documentation of the perl public API generated by
-embed.pl, specifically a listing of functions, macros, flags, and variables
+F<embed.pl>, specifically a listing of functions, macros, flags, and variables
 that may be used by extension writers.  L<At the end|/Undocumented functions>
 is a list of functions which have yet to be documented.  The interfaces of
 those are subject to change without notice.  Any functions not listed here are
 that may be used by extension writers.  L<At the end|/Undocumented functions>
 is a list of functions which have yet to be documented.  The interfaces of
 those are subject to change without notice.  Any functions not listed here are
@@ -314,11 +397,6 @@ But the ordinals of characters differ between ASCII, EBCDIC, and
 the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes
 than in UTF-8.
 
 the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes
 than in UTF-8.
 
-Also, on some EBCDIC machines, functions that are documented as operating on
-US-ASCII (or Basic Latin in Unicode terminology) may in fact operate on all
-256 characters in the EBCDIC range, not just the subset corresponding to
-US-ASCII.
-
 The listing below is alphabetical, case insensitive.
 
 _EOB_
 The listing below is alphabetical, case insensitive.
 
 _EOB_
@@ -343,7 +421,9 @@ L<perlguts>, L<perlxs>, L<perlxstut>, L<perlintern>
 
 _EOE_
 
 
 _EOE_
 
-my @missing_guts = grep $funcflags{$_}{flags} !~ /A/ && !$docs{guts}{$_}, keys %funcflags;
+# List of non-static internal functions
+my @missing_guts =
+ grep $funcflags{$_}{flags} !~ /[As]/ && !$docs{guts}{$_}, keys %funcflags;
 
 output('perlintern', <<'END', $docs{guts}, \@missing_guts, <<'END');
 =head1 NAME
 
 output('perlintern', <<'END', $docs{guts}, \@missing_guts, <<'END');
 =head1 NAME
Unnamed repository; edit this file 'description' to name the repository.