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,
my %docs;
my %funcflags;
-my %macro = (
- ax => 1,
- items => 1,
- ix => 1,
- svtype => 1,
- );
my %missing;
my $curheader = "Unknown section";
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;
=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 = "";
$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
}
}
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 = '' }
}
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";
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
|=head1 DESCRIPTION
|X<Perl API> X<API> X<api>
|
-|This file contains the documentation of the perl public API generated by
-|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. 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<embed.pl>. 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<At the end|/Undocumented functions> 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<NUL> characters. Sometimes in the documentation a Perl string is referred
|=head1 AUTHORS
|
|Until May 1997, this document was maintained by Jeff Okamoto
-|<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
+|<okamoto\@corp.hp.com>. 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 <roehrich@cray.com>.
+|API Listing originally by Dean Roehrich <roehrich\@cray.com>.
|
|Updated to be autogenerated from comments in the source by Benjamin Stuhl.
|
|=head1 SEE ALSO
|
-|L<perlguts>, L<perlxs>, L<perlxstut>, L<perlintern>
-|
+$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<internal>
|format but are not marked as part of the Perl API. In other words,
|B<they are not for use in extensions>!
|
-END
+_EOB_
|
|=head1 AUTHORS
|
|
|=head1 SEE ALSO
|
-|L<perlguts>, L<perlapi>
-|
-END
+$other_places_intern
+_EOE_
https://perl5.git.perl.org / perl5.git / blobdiff