perlapi: Clarify process of using undocumented globals
authorKarl Williamson <khw@cpan.org>
Wed, 18 Jun 2014 00:49:53 +0000 (18:49 -0600)
committerKarl Williamson <khw@cpan.org>
Thu, 1 Oct 2015 02:38:47 +0000 (20:38 -0600)
One should send email to p5p first to get the go-ahead for documenting
and using an undocumented function or global variable.

autodoc.pl
perlvars.h

index b27fc4d..4a55c3c 100644 (file)
@@ -304,11 +304,14 @@ 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).
+If you feel you need to use one of these functions, first send email to
+L<perl5-porters@perl.org|mailto:perl5-porters@perl.org>.  It may be
+that there is a good reason for the function not being documented, and it
+should be removed from this list; or it may just be that no one has gotten
+around to documenting it.  In the latter case, you will be asked to submit a
+patch to document the function.  Once your patch is accepted, it will indicate
+that the interface is stable (unless it is explicitly marked otherwise) and
+usable by you.
 
 =over
 
index 7bafa40..86a369e 100644 (file)
 
 /*
 =head1 Global Variables
-
 These variables are global to an entire process.  They are shared between
-all interpreters and all threads in a process.
+all interpreters and all threads in a process.  Any variables not documented
+here may be changed or removed without notice, so don't use them!
+If you feel you really do need to use an unlisted variable, first send email to
+L<perl5-porters@perl.org|mailto:perl5-porters@perl.org>.  It may be that
+someone there will point out a way to accomplish what you need without using an
+internal variable.  But if not, you should get a go-ahead to document and then
+use the variable.
 
 =cut
 */