#
# 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
-# 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.
+# '=head1' are the only headings looked for. If the first non-blank 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, $header_doc);
+
+ # Count lines easier
+ my $get_next_line = sub { $line++; return <$fh> };
+
FUNC:
- while (defined($in = <$fh>)) {
+ 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;
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 the next non-space line begins with a word char, then it is
+ # the start of heading-ldevel documentation.
+ if (defined($doc = $get_next_line->())) {
+ # Skip over empty lines
+ while ($doc =~ /^\s+$/) {
+ if (! defined($doc = $get_next_line->())) {
+ next FUNC;
+ }
+ }
+
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>)) {
+ while (defined($doc = $get_next_line->())) {
if ($doc =~ /^=\w/) {
$in = $doc;
redo FUNC;
}
- $line++;
if ($doc =~ m:^\s*\*/$:) {
warn "=cut missing? $file:$line:$doc";;
}
next FUNC;
}
- $line++;
if ($in =~ /^=for\s+apidoc\s+(.*?)\s*\n/) {
my $proto = $1;
$proto = "||$proto" unless $proto =~ /\|/;
my($flags, $ret, $name, @args) = split /\|/, $proto;
my $docs = "";
DOC:
- while (defined($doc = <$fh>)) {
- $line++;
+ while (defined($doc = $get_next_line->())) {
last DOC if $doc =~ /^=\w+/;
if ($doc =~ m:^\*/$:) {
warn "=cut missing? $file:$line:$doc";;
print $fh "=for hackers\nFound in file $file\n\n";
}
+sub sort_helper {
+ # Do a case-insensitive dictionary sort, with only alphabetics
+ # significant, falling back to using everything for determinancy
+ return (uc($a =~ s/[[^:alpha]]//r) cmp uc($b =~ s/[[^:alpha]]//r))
+ || uc($a) cmp uc($b)
+ || $a cmp $b;
+}
+
sub output {
my ($podname, $header, $dochash, $missing, $footer) = @_;
my $fh = open_new("pod/$podname.pod", undef,
print $fh $header;
my $key;
- # case insensitive sort, with fallback for determinacy
- for $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$dochash) {
+ for $key (sort sort_helper keys %$dochash) {
my $section = $dochash->{$key};
print $fh "\n=head1 $key\n\n";
}
print $fh "=over 8\n\n";
- # Again, fallback for determinacy
- for my $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$section) {
+ for my $key (sort sort_helper keys %$section) {
docout($fh, $key, $section->{$key});
}
print $fh "\n=back\n";