From ba4591a5abe7e0d129a8a810764a6e21278c8604 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Sun, 2 Dec 2012 22:14:07 -0700 Subject: [PATCH] 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. --- autodoc.pl | 13 ++++++++----- embed.fnc | 8 ++++++-- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/autodoc.pl b/autodoc.pl index 3734884..3b39696 100644 --- 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 --- 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 -- 2.7.4