X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/5514c4f10ad12603528732f1bd16d15059a26369..68678ef8cefed0b23914458ad222d00aa288b504:/autodoc.pl diff --git a/autodoc.pl b/autodoc.pl index 5aaab29..b8d46b3 100644 --- a/autodoc.pl +++ b/autodoc.pl @@ -35,6 +35,29 @@ if (@ARGV) { require './regen/regen_lib.pl'; require './regen/embed_lib.pl'; +my @specialized_docs = sort qw( perlguts + perlxs + perlxstut + perlclib + warnings + perlapio + perlcall + perlfilter + perlmroapi + config.h + ); +sub name_in_pod($) { + my $name = shift; + return "F<$name>" if $name =~ /\./; + return "L<$name>"; +} +my $other_places_api = join " ", map { name_in_pod($_) } sort @specialized_docs, 'perlintern'; +my $other_places_intern = join " ", map { name_in_pod($_) } sort @specialized_docs, 'perlapi'; + +@specialized_docs = map { name_in_pod($_) } sort @specialized_docs; +$specialized_docs[-1] =~ s/^/and /; +my $specialized_docs = join ", ", @specialized_docs; + # # See database of global and static function prototypes in embed.fnc # This is used to generate prototype headers under various configurations, @@ -44,12 +67,6 @@ require './regen/embed_lib.pl'; my %docs; my %funcflags; -my %macro = ( - ax => 1, - items => 1, - ix => 1, - svtype => 1, - ); my %missing; my $curheader = "Unknown section"; @@ -63,11 +80,6 @@ sub autodoc ($$) { # parse a file and extract documentation info FUNC: while (defined($in = $get_next_line->())) { - if ($in =~ /^#\s*define\s+([A-Za-z_][A-Za-z_0-9]+)\(/ && - ($file ne 'embed.h' || $file ne 'proto.h')) { - $macro{$1} = $file; - next FUNC; - } if ($in=~ /^=head1 (.*)/) { $curheader = $1; @@ -119,6 +131,11 @@ Expected: =for apidoc flags|returntype|name =for apidoc name EOS + die "flag $1 is not legal (for function $name (from $file))" + if $flags =~ / ( [^AabCDdEefhiMmNnTOoPpRrSsUuWXx] ) /x; + next FUNC if $flags =~ /h/; + + die "'u' flag must also have 'm' flag' for $name" if $flags =~ /u/ && $flags !~ /m/; warn ("'$name' not \\w+ in '$proto_in_file' in $file") if $flags !~ /N/ && $name !~ / ^ [_[:alpha:]] \w* $ /x; my $docs = ""; @@ -145,6 +162,7 @@ DOC: $flags = $embed_docref->{'flags'}; warn "embed.fnc entry '$name' missing 'd' flag" unless $flags =~ /d/; + next FUNC if $flags =~ /h/; $ret = $embed_docref->{'retval'}; @args = @{$embed_docref->{args}}; } elsif ($flags !~ /m/) { # Not in embed.fnc, is missing if not a @@ -233,7 +251,7 @@ removed without notice.\n\n$docs" if $flags =~ /x/; } } my $args = ''; - if ($p && $flags !~ /T/) { + if ($flags !~ /T/ && ($p || ($flags =~ /m/ && $name =~ /^Perl_/))) { $args = @args ? "pTHX_ " : "pTHX"; if ($long_args) { print $fh $args; $args = '' } } @@ -357,7 +375,7 @@ foreach (@{(setup_embed())[0]}) { open my $fh, '<', 'MANIFEST' or die "Can't open MANIFEST: $!"; while (my $line = <$fh>) { - next unless my ($file) = $line =~ /^(\S+\.[ch])\t/; + next unless my ($file) = $line =~ /^(\S+\.(?:[ch]|pod))\t/; open F, '<', $file or die "Cannot open $file for docs: $!\n"; $curheader = "Functions in file $file\n"; @@ -368,25 +386,23 @@ close $fh or die "Error whilst reading MANIFEST: $!"; for (sort keys %funcflags) { next unless $funcflags{$_}{flags} =~ /d/; + next if $funcflags{$_}{flags} =~ /h/; warn "no docs for $_\n" } foreach (sort keys %missing) { - next if $macro{$_}; - # Heuristics for known not-a-function macros: - next if /^[A-Z]/; - next if /^dj?[A-Z]/; - warn "Function '$_', documented in $missing{$_}, not listed in embed.fnc"; } # 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 nor -# deprecated. -my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && $funcflags{$_}{flags} !~ /[xD]/ && !$docs{api}{$_}, keys %funcflags; -output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<'_EOE_'); +# List of funcs in the public API that aren't also marked as core-only, +# experimental nor deprecated. +my @missing_api = grep $funcflags{$_}{flags} =~ /A/ + && $funcflags{$_}{flags} !~ /[xD]/ + && !$docs{api}{$_}, keys %funcflags; +output('perlapi', <<"_EOB_", $docs{api}, \@missing_api, <<"_EOE_"); |=encoding UTF-8 | |=head1 NAME @@ -396,14 +412,18 @@ output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<'_EOE_'); |=head1 DESCRIPTION |X X X | -|This file contains the documentation of the perl public API generated by -|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. Anything not listed here is -|not part of the public API, and should not be used by extension writers at -|all. For these reasons, blindly using functions listed in proto.h is to be -|avoided when writing extensions. +|This file contains most of the documentation of the perl public API, as +|generated by F. Specifically, it is a listing of functions, +|macros, flags, and variables that may be used by extension writers. Some +|specialized items are instead documented in $specialized_docs. +| +|L is a list of functions which have yet +|to be documented. Patches welcome! The interfaces of these are subject to +|change without notice. +| +|Anything not listed here is not part of the public API, and should not be +|used by extension writers at all. For these reasons, blindly using functions +|listed in proto.h is to be avoided when writing extensions. | |In Perl, unlike C, a string of characters may generally contain embedded |C characters. Sometimes in the documentation a Perl string is referred @@ -449,28 +469,27 @@ _EOB_ |=head1 AUTHORS | |Until May 1997, this document was maintained by Jeff Okamoto -|. It is now maintained as part of Perl itself. +|. It is now maintained as part of Perl itself. | |With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, |Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil |Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, |Stephen McCamant, and Gurusamy Sarathy. | -|API Listing originally by Dean Roehrich . +|API Listing originally by Dean Roehrich . | |Updated to be autogenerated from comments in the source by Benjamin Stuhl. | |=head1 SEE ALSO | -|L, L, L, L -| +$other_places_api _EOE_ # 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'); +output('perlintern', <<'_EOB_', $docs{guts}, \@missing_guts, <<"_EOE_"); |=head1 NAME | |perlintern - autogenerated documentation of purely B @@ -484,7 +503,7 @@ output('perlintern', <<'END', $docs{guts}, \@missing_guts, <<'END'); |format but are not marked as part of the Perl API. In other words, |B! | -END +_EOB_ | |=head1 AUTHORS | @@ -494,6 +513,5 @@ END | |=head1 SEE ALSO | -|L, L -| -END +$other_places_intern +_EOE_