autodoc.pl: Clarify use of undocumented fcns

perlapi.pod was changed to list all the undocumented functions.  The
introductory text was not updated at that time.  Now every public API
function is at least listed in this pod.  Clarify that functions not
listed are not public and should not be used, and add a plea for
documenting the ones which are missing theirs.

1 files changed, 21 insertions, 10 deletions

diff --git a/autodoc.pl b/autodoc.pl
index 91963ca5ac..2e5217e92b 100644
--- a/autodoc.pl
+++ b/autodoc.pl
@@ -183,14 +183,23 @@ _EOH_
 
     if (@$missing) {
         print $fh "\n=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 <<'_EOB_';
+Some functions are currently undocumented; use at your own risk, as the
+interfaces are subject to change.  If you use one of these, do everyone a
+favor by creating documentation for it.  The acceptance of your patch will
+indicate that the interface is stable (unless it is explicitly marked
+otherwise).  The undocumented functions are:
+
+=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:
@@ -276,10 +285,12 @@ X<Perl API> X<API> X<api>
 
 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,