update Perl::OSType from 1.002 to 1.003

[perl5.git] / autodoc.pl

diff --git a/autodoc.pl b/autodoc.pl
index 139c313..925f2f5 100644 (file)
--- a/autodoc.pl
+++ b/autodoc.pl
@@ -186,14 +186,50 @@ 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";
 }
     }
     print $fh "=for hackers\nFound in file $file\n\n";
 }


@@ -235,14 +271,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_';
+    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
 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.
+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 them, 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).
+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
 


@@ -339,7 +385,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


@@ -369,11 +415,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_


@@ -398,7 +439,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