Better POD for newSVrv

It takes me a couple times to slowly read the description to realize
what this does. The "its reference count is 1" can be misread to mean
someone must mortalize the return value of newSVrv. The "Creates
a new SV for the RV, C<rv>, to point to." can be misread to mean that
newSVrv is a macro, and will do an &() on rv to create a total of
two new SVs. An SvRV pointing to a posssibly blessed undef SV.
This is also wrong. Adding "existing" makes the point that rv
will not be created in this call.

diff --git a/sv.c b/sv.c
index 3e3a5c7..64862ea 100644 (file)
--- a/sv.c
+++ b/sv.c
@@ -9503,10 +9503,10 @@ Perl_sv_isa(pTHX_ SV *sv, const char *const name)
 /*
 =for apidoc newSVrv
 
-Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
-it will be upgraded to one.  If C<classname> is non-null then the new SV will
-be blessed in the specified package.  The new SV is returned and its
-reference count is 1.
+Creates a new SV for the existing RV, C<rv>, to point to.  If C<rv> is not an
+RV then it will be upgraded to one.  If C<classname> is non-null then the new
+SV will be blessed in the specified package.  The new SV is returned and its
+reference count is 1. The reference count 1 is owned by C<rv>.
 
 =cut
 */