This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
embed.fnc: Note that 'A' functions not necessarily public API
authorKarl Williamson <public@khwilliamson.com>
Mon, 3 Dec 2012 05:14:07 +0000 (22:14 -0700)
committerKarl Williamson <public@khwilliamson.com>
Sun, 9 Dec 2012 17:27:18 +0000 (10:27 -0700)
An 'M' in a function entry means that undocumented functions are
suppressed from perlapi.pod.  Change the comments in embed.fnc to
indicate that, and the text in perlapi to warn against using unlisted
functions.

autodoc.pl
embed.fnc

index 3734884..3b39696 100644 (file)
@@ -274,11 +274,14 @@ _EOH_
     print $fh $podname eq 'perlapi' ? <<'_EOB_' : <<'_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).
+interfaces are subject to change.  Functions that are not listed in this
+document are not intended for public use, and should NOT be used under any
+circumstances.
+
+If you use one of the undocumented functions below, 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
 
index 84c0b19..fc2c2b8 100644 (file)
--- a/embed.fnc
+++ b/embed.fnc
 :
 : flags are single letters with following meanings:
 :
-:   A  Member of public API:
+:   A  Available fully everywhere (usually part of the public API):
 :
 :         add entry to the list of exported symbols (unless x or m);
-:         any doc entry goes in perlapi.pod rather than perlintern.pod
+:         any doc entry goes in perlapi.pod rather than perlintern.pod.  If no
+:           documentation is furnished for this function, and M is also
+:           specified, the function is not listed as part of the public API.
+:           If M isn't specified and no documentation is furnished, the
+:           function is listed in perlapi as existing and being undocumented
 :         makes '#define foo Perl_foo' scope not just for PERL_CORE/PERL_EXT
 :
 :      If the function is only exported for use in a public