first step to documenting the Internals namespace

After discussion, we have decided to document Internals. This is a
first step doing so, with lib/Internals.pod. At the same time I
updated sv.h that there were equivalents for SvREFCNT and SvREADONLY
in the Internals namespace, this required adding docs for SvREADONLY.

I also tweaked the test name in Porting/Maintainers.pm
so that it pointed at Porting/Maintainers.pl to make it more obvious
how to specify a maintainer for a new file.

5 files changed, 91 insertions, 3 deletions

diff --git a/MANIFEST b/MANIFEST
index 606b654d0f..4eceaebe30 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -4418,6 +4418,7 @@ lib/h2ph.t			See if h2ph works like it should
 lib/h2xs.t			See if h2xs produces expected lists of files
 lib/integer.pm			For "use integer"
 lib/integer.t			For "use integer" testing
+lib/Internals.pod		Document the Internals namespace (implemented by universal.c)
 lib/Internals.t			For Internals::* testing
 lib/less.pm			For "use less"
 lib/less.t			See if less support works
diff --git a/Porting/Maintainers.pl b/Porting/Maintainers.pl
index 64135bfa88..58a74b6a59 100755
--- a/Porting/Maintainers.pl
+++ b/Porting/Maintainers.pl
@@ -1467,6 +1467,7 @@ use File::Glob qw(:case);
                 lib/FileHandle.{pm,t}
                 lib/FindBin.{pm,t}
                 lib/Getopt/Std.{pm,t}
+                lib/Internals.pod
                 lib/Internals.t
                 lib/meta_notation.{pm,t}
                 lib/Net/hostent.{pm,t}
diff --git a/Porting/Maintainers.pm b/Porting/Maintainers.pm
index 6b28ea7e58..ef56abb912 100644
--- a/Porting/Maintainers.pm
+++ b/Porting/Maintainers.pm
@@ -22,7 +22,7 @@ use vars qw(@ISA @EXPORT_OK $VERSION);
 		show_results process_options files_to_modules
 		finish_tap_output
 		reload_manifest);
-$VERSION = 0.10;
+$VERSION = 0.11;
 
 require Exporter;
 
@@ -356,7 +356,7 @@ sub duplicated_maintainers {
 
 sub warn_maintainer {
     my $name = shift;
-    ok($files{$name}, "$name has a maintainer");
+    ok($files{$name}, "$name has a maintainer (see Porting/Maintainer.pl)");
 }
 
 sub missing_maintainers {
diff --git a/lib/Internals.pod b/lib/Internals.pod
new file mode 100644
index 0000000000..28f6711b30
--- /dev/null
+++ b/lib/Internals.pod
@@ -0,0 +1,69 @@
+=head1 NAME
+
+Internals - Reserved special namespace for internals related functions
+
+=head1 SYNOPSIS
+
+    $is_ro= Internals::SvREADONLY($x)
+    $refcnt= Internals::SvREFCNT($x)
+
+=head1 DESCRIPTION
+
+The Internals namespace is used by the core Perl development team to
+expose certain low level internals routines for testing and other purposes.
+
+In theory these routines were not and are not intended to be used outside
+of the perl core, and are subject to change and removal at any time.
+
+In practice people have come to depend on these over the years, despite
+being historically undocumented, so we will provide some level of
+forward compatibility for some time. Nevertheless you can assume that any
+routine documented here is experimental or deprecated and you should find
+alternatives to their use.
+
+=head2 FUNCTIONS
+
+=over 4
+
+=item SvREFCNT(THING [, $value])
+
+Historically Perl has been a refcounted language. This means that each
+variable tracks how many things reference it, and when the variable is no
+longer referenced it will automatically free itself. In theory Perl code
+should not have to care about this, and in a future version Perl might
+change to some other strategy, although in practice this is unlikely.
+
+This function allows one to violate the abstraction of variables and get
+or set the refcount of a variable, and in generally is really only useful
+in code that is testing refcount behavior.
+
+*NOTE* You are strongly discouraged from using this function in non-test
+code and especially discouraged from using the set form of this function.
+The results of doing so may result in segmentation faults or other undefined
+behavior.
+
+=item SvREADONLY(THING, [, $value])
+
+Set or get whether a variable is readonly or not. Exactly what the
+readonly flag means depend on the type of the variable affected and the
+version of perl used.
+
+You are strongly discouraged from using this function directly. It is used
+by various core modules, like C<Hash::Util>, and the C<constant> pragma
+to implement higher-level behavior which should be used instead.
+
+See the core implementation for the exact meaning of the readonly flag for
+each internal variable type.
+
+=back
+
+=head1 AUTHOR
+
+Perl core development team.
+
+=head1 SEE ALSO
+
+L<perlguts>
+universal.c
+
+=cut
diff --git a/sv.h b/sv.h
index db42a66715..07719a6c08 100644
--- a/sv.h
+++ b/sv.h
@@ -269,7 +269,8 @@ struct p5rx {
 =head1 SV Manipulation Functions
 
 =for apidoc Am|U32|SvREFCNT|SV* sv
-Returns the value of the object's reference count.
+Returns the value of the object's reference count. Exposed
+to perl code via Internals::SvREFCNT().
 
 =for apidoc Am|SV*|SvREFCNT_inc|SV* sv
 Increments the reference count of the given SV, returning the SV.
@@ -1089,6 +1090,22 @@ C<sv_force_normal> does nothing.
 #define SvOBJECT_on(sv)		(SvFLAGS(sv) |= SVs_OBJECT)
 #define SvOBJECT_off(sv)	(SvFLAGS(sv) &= ~SVs_OBJECT)
 
+/*
+=for apidoc Am|U32|SvREADONLY|SV* sv
+Returns true if the argument is readonly, otherwise returns false.
+Exposed to to perl code via Internals::SvREADONLY().
+
+=for apidoc Am|U32|SvREADONLY_on|SV* sv
+Mark an object as readonly. Exactly what this means depends on the object
+type. Exposed to perl code via Internals::SvREADONLY().
+
+=for apidoc Am|U32|SvREADONLY_off|SV* sv
+Mark an object as not-readonly. Exactly what this mean depends on the
+object type. Exposed to perl code via Internals::SvREADONLY().
+
+=cut
+*/
+
 #define SvREADONLY(sv)		(SvFLAGS(sv) & (SVf_READONLY|SVf_PROTECT))
 #ifdef PERL_CORE
 # define SvREADONLY_on(sv)	(SvFLAGS(sv) |= (SVf_READONLY|SVf_PROTECT))