embed.fnc: Note that 'A' functions not necessarily public API

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.

diff --git a/autodoc.pl b/autodoc.pl
index 3734884..3b39696 100644 (file)
--- a/autodoc.pl
+++ b/autodoc.pl
@@ -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
 

diff --git a/embed.fnc b/embed.fnc
index 84c0b19..fc2c2b8 100644 (file)
--- a/embed.fnc
+++ b/embed.fnc
@@ -10,10 +10,14 @@
 :
 : 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