X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/2616800a6ed97301803de10c5e05d41b22088ec8..bfb4a93c2cc1dd3a99d8a1038cdb1786d33e8712:/autodoc.pl diff --git a/autodoc.pl b/autodoc.pl index c1e2578..bff2094 100644 --- a/autodoc.pl +++ b/autodoc.pl @@ -13,8 +13,7 @@ # 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 @@ -25,6 +24,14 @@ 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, @@ -113,6 +120,7 @@ DOC: 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; } @@ -171,8 +179,15 @@ sub docout ($$$) { # output the docs for one function 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" @@ -236,17 +251,11 @@ removed without notice.\n\n" if $flags =~ /x/; 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 -*- + my $fh = open_new("pod/$podname.pod", undef, + {by => "$0 extracting documentation", + from => 'the C source files'}, 1); -!!!!!!! DO NOT EDIT THIS FILE !!!!!!! -This file is built by $0 extracting documentation from the C source -files. - -_EOH_ + print $fh $header; my $key; # case insensitive sort, with fallback for determinacy @@ -274,11 +283,14 @@ _EOH_ 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. +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 @@ -295,41 +307,15 @@ _EOB_ } 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: $!"; -} - -if (@ARGV) { - my $workdir = shift; - chdir $workdir - or die "Couldn't chdir to '$workdir': $!"; + read_only_bottom_close_and_rename($fh); } -open IN, "embed.fnc" or die $!; - -while () { - chomp; - next if /^:/; - while (s|\\\s*$||) { - $_ .= ; - 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, @@ -338,21 +324,19 @@ while () { }; } -my $file; # 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: $!"; - ; -}; +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"; } +close $fh or die "Error whilst reading MANIFEST: $!"; for (sort keys %funcflags) { next unless $funcflags{$_}{flags} =~ /d/; @@ -371,8 +355,9 @@ foreach (sort keys %missing) { # walk table providing an array of components in each line to # subroutine, printing the result -# List of funcs in the public API that aren't also marked as experimental. -my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && $funcflags{$_}{flags} !~ /M/ && !$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 @@ -382,7 +367,7 @@ perlapi - autogenerated documentation for the perl public API X X X This file contains the documentation of the perl public API generated by -embed.pl, specifically a listing of functions, macros, flags, and variables +F, specifically a listing of functions, macros, flags, and variables that may be used by extension writers. L 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 @@ -412,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. -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_ @@ -441,7 +421,9 @@ L, L, L, L _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