#
# This script is normally invoked as part of 'make all', but is also
# called from from regen.pl.
+#
+# '=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;
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]+)\(/ &&
}
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++;
$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;
removed without notice.\n\n" 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"
+ if $flags =~ /o/;
print $fh "=item $name\nX<$name>\n$docs";
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
print $fh "\t$ret\t$name";
print $fh "(" . join(", ", @args) . ")";
# 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});
}
if (@$missing) {
- print $fh "=head1 Undocumented functions\n\n";
- print $fh "These functions are currently undocumented:\n\n=over\n\n";
- for my $missing (sort @$missing) {
- print $fh "=item $missing\nX<$missing>\n\n";
- }
- print $fh "=back\n\n";
+ print $fh "\n=head1 Undocumented functions\n\n";
+ print $fh <<'_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.
+
+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).
+
+=over
+
+_EOB_
+ for my $missing (sort @$missing) {
+ print $fh "=item $missing\nX<$missing>\n\n";
}
+ print $fh "=back\n\n";
+}
- print $fh $footer, <<'_EOF_';
+print $fh $footer, <<'_EOF_';
=cut
ex: set ro:
This file contains the documentation of the perl public API generated by
embed.pl, specifically a listing of functions, macros, flags, and variables
-that may be used by extension writers. The interfaces of any functions that
-are not listed here are subject to change without notice. For this reason,
-blindly using functions listed in proto.h is to be avoided when writing
-extensions.
+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
+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.
Note that all Perl API global variables must be referenced with the C<PL_>
prefix. Some macros are provided for compatibility with the older,