list undocumented API and internal functions in perlapi.pod and perlintern.pod
authorTony Cook <tony@develop-help.com>
Mon, 1 Mar 2010 12:44:54 +0000 (23:44 +1100)
committerRafael Garcia-Suarez <rgs@consttype.org>
Mon, 8 Mar 2010 09:28:45 +0000 (10:28 +0100)
List any functions from embed.fnc that don't have documentation in
their own section of perlapi/perlintern as a reminder to either
document them, remove them or perhaps flag them as undeserving of
documentation.

autodoc.pl

index 28ca96e..a88af9c 100644 (file)
@@ -150,7 +150,7 @@ removed without notice.\n\n" if $flags =~ /x/;
 }
 
 sub output {
-    my ($podname, $header, $dochash, $footer) = @_;
+    my ($podname, $header, $dochash, $missing, $footer) = @_;
     my $filename = "pod/$podname.pod";
     open my $fh, '>', $filename or die "Can't open $filename: $!";
 
@@ -175,6 +175,15 @@ _EOH_
        print $fh "\n=back\n";
     }
 
+    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 $footer, <<'_EOF_';
 =cut
 
@@ -250,7 +259,8 @@ foreach (sort keys %missing) {
 # walk table providing an array of components in each line to
 # subroutine, printing the result
 
-output('perlapi', <<'_EOB_', $docs{api}, <<'_EOE_');
+my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && !$docs{api}{$_}, keys %funcflags;
+output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<'_EOE_');
 =head1 NAME
 
 perlapi - autogenerated documentation for the perl public API
@@ -316,7 +326,9 @@ perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
 
 _EOE_
 
-output('perlintern', <<'END', $docs{guts}, <<'END');
+my @missing_guts = grep $funcflags{$_}{flags} !~ /A/ && !$docs{guts}{$_}, keys %funcflags;
+
+output('perlintern', <<'END', $docs{guts}, \@missing_guts, <<'END');
 =head1 NAME
 
 perlintern - autogenerated documentation of purely B<internal>