X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/42b23152d57f32c395f1809eda6f29e3e22d2c5c..6a4c4cd41c54334613baa6cada2145fd51e180e6:/autodoc.pl diff --git a/autodoc.pl b/autodoc.pl index cf82639..788dc35 100644 --- a/autodoc.pl +++ b/autodoc.pl @@ -273,6 +273,11 @@ sub sort_helper { sub output { my ($podname, $header, $dochash, $missing, $footer) = @_; + # + # strip leading '|' from each line which had been used to hide + # pod from pod checkers. + s/^\|//gm for $header, $footer; + my $fh = open_new("pod/$podname.pod", undef, {by => "$0 extracting documentation", from => 'the C source files'}, 1); @@ -315,17 +320,13 @@ around to documenting it. In the latter case, you will be asked to submit a patch to document the function. Once your patch is accepted, it will indicate that the interface is stable (unless it is explicitly marked otherwise) and usable by you. - -=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 - _EOB_ + print $fh "\n=over\n\n"; + for my $missing (sort @$missing) { print $fh "=item $missing\nX<$missing>\n\n"; } @@ -383,83 +384,83 @@ foreach (sort keys %missing) { # deprecated. my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && $funcflags{$_}{flags} !~ /[MD]/ && !$docs{api}{$_}, keys %funcflags; output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<'_EOE_'); -=encoding UTF-8 - -=head1 NAME - -perlapi - autogenerated documentation for the perl public API - -=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. - -In Perl, unlike C, a string of characters may generally contain embedded -C characters. Sometimes in the documentation a Perl string is referred -to as a "buffer" to distinguish it from a C string, but sometimes they are -both just referred to as strings. - -Note that all Perl API global variables must be referenced with the C -prefix. Again, those not listed here are not to be used by extension writers, -and can be changed or removed without notice; same with macros. -Some macros are provided for compatibility with the older, -unadorned names, but this support may be disabled in a future release. - -Perl was originally written to handle US-ASCII only (that is characters -whose ordinal numbers are in the range 0 - 127). -And documentation and comments may still use the term ASCII, when -sometimes in fact the entire range from 0 - 255 is meant. - -The non-ASCII characters below 256 can have various meanings, depending on -various things. (See, most notably, L.) But usually the whole -range can be referred to as ISO-8859-1. Often, the term "Latin-1" (or -"Latin1") is used as an equivalent for ISO-8859-1. But some people treat -"Latin1" as referring just to the characters in the range 128 through 255, or -somethimes from 160 through 255. -This documentation uses "Latin1" and "Latin-1" to refer to all 256 characters. - -Note that Perl can be compiled and run under either ASCII or EBCDIC (See -L). Most of the documentation (and even comments in the code) -ignore the EBCDIC possibility. -For almost all purposes the differences are transparent. -As an example, under EBCDIC, -instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so -whenever this documentation refers to C -(and variants of that name, including in function names), -it also (essentially transparently) means C. -But the ordinals of characters differ between ASCII, EBCDIC, and -the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy a different -number of bytes than in UTF-8. - -The listing below is alphabetical, case insensitive. - +|=encoding UTF-8 +| +|=head1 NAME +| +|perlapi - autogenerated documentation for the perl public API +| +|=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. +| +|In Perl, unlike C, a string of characters may generally contain embedded +|C characters. Sometimes in the documentation a Perl string is referred +|to as a "buffer" to distinguish it from a C string, but sometimes they are +|both just referred to as strings. +| +|Note that all Perl API global variables must be referenced with the C +|prefix. Again, those not listed here are not to be used by extension writers, +|and can be changed or removed without notice; same with macros. +|Some macros are provided for compatibility with the older, +|unadorned names, but this support may be disabled in a future release. +| +|Perl was originally written to handle US-ASCII only (that is characters +|whose ordinal numbers are in the range 0 - 127). +|And documentation and comments may still use the term ASCII, when +|sometimes in fact the entire range from 0 - 255 is meant. +| +|The non-ASCII characters below 256 can have various meanings, depending on +|various things. (See, most notably, L.) But usually the whole +|range can be referred to as ISO-8859-1. Often, the term "Latin-1" (or +|"Latin1") is used as an equivalent for ISO-8859-1. But some people treat +|"Latin1" as referring just to the characters in the range 128 through 255, or +|somethimes from 160 through 255. +|This documentation uses "Latin1" and "Latin-1" to refer to all 256 characters. +| +|Note that Perl can be compiled and run under either ASCII or EBCDIC (See +|L). Most of the documentation (and even comments in the code) +|ignore the EBCDIC possibility. +|For almost all purposes the differences are transparent. +|As an example, under EBCDIC, +|instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so +|whenever this documentation refers to C +|(and variants of that name, including in function names), +|it also (essentially transparently) means C. +|But the ordinals of characters differ between ASCII, EBCDIC, and +|the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy a different +|number of bytes than in UTF-8. +| +|The listing below is alphabetical, case insensitive. +| _EOB_ - -=head1 AUTHORS - -Until May 1997, this document was maintained by Jeff Okamoto -. 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 . - -Updated to be autogenerated from comments in the source by Benjamin Stuhl. - -=head1 SEE ALSO - -L, L, L, L - +| +|=head1 AUTHORS +| +|Until May 1997, this document was maintained by Jeff Okamoto +|. 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 . +| +|Updated to be autogenerated from comments in the source by Benjamin Stuhl. +| +|=head1 SEE ALSO +| +|L, L, L, L +| _EOE_ # List of non-static internal functions @@ -467,29 +468,29 @@ my @missing_guts = grep $funcflags{$_}{flags} !~ /[As]/ && !$docs{guts}{$_}, keys %funcflags; output('perlintern', <<'END', $docs{guts}, \@missing_guts, <<'END'); -=head1 NAME - -perlintern - autogenerated documentation of purely B - Perl functions - -=head1 DESCRIPTION -X X - -This file is the autogenerated documentation of functions in the -Perl interpreter that are documented using Perl's internal documentation -format but are not marked as part of the Perl API. In other words, -B! - +|=head1 NAME +| +|perlintern - autogenerated documentation of purely B +| Perl functions +| +|=head1 DESCRIPTION +|X X +| +|This file is the autogenerated documentation of functions in the +|Perl interpreter that are documented using Perl's internal documentation +|format but are not marked as part of the Perl API. In other words, +|B! +| END - -=head1 AUTHORS - -The autodocumentation system was originally added to the Perl core by -Benjamin Stuhl. Documentation is by whoever was kind enough to -document their functions. - -=head1 SEE ALSO - -L, L - +| +|=head1 AUTHORS +| +|The autodocumentation system was originally added to the Perl core by +|Benjamin Stuhl. Documentation is by whoever was kind enough to +|document their functions. +| +|=head1 SEE ALSO +| +|L, L +| END