PATCH: [perl #130801] perlapi: Clarify SvIV/SvUV/SvNV behavior

[The committer made a few changes for improved readability]

1 files changed, 33 insertions, 18 deletions

diff --git a/sv.h b/sv.h
index 5e9c5b6881..51e9b0ba66 100644
--- a/sv.h
+++ b/sv.h
@@ -1521,43 +1521,58 @@ Like C<SvPV> but doesn't set a length variable.
 Like C<SvPV_nolen> but doesn't process magic.
 
 =for apidoc Am|IV|SvIV|SV* sv
-Coerces the given SV to an integer and returns it.  See C<L</SvIVx>> for a
-version which guarantees to evaluate C<sv> only once.
+Coerces the given SV to IV and returns it.  The returned value in many
+circumstances will get stored in C<sv>'s IV slot, but not in all cases.  (Use
+C<L</sv_setiv>> to make sure it does).
+
+See C<L</SvIVx>> for a version which guarantees to evaluate C<sv> only once.
 
 =for apidoc Am|IV|SvIV_nomg|SV* sv
 Like C<SvIV> but doesn't process magic.
 
 =for apidoc Am|IV|SvIVx|SV* sv
-Coerces the given SV to an integer and returns it.
-Guarantees to evaluate C<sv> only once.  Only use
-this if C<sv> is an expression with side effects,
-otherwise use the more efficient C<SvIV>.
+Coerces the given SV to IV and returns it.  The returned value in many
+circumstances will get stored in C<sv>'s IV slot, but not in all cases.  (Use
+C<L</sv_setiv>> to make sure it does).
+
+This form guarantees to evaluate C<sv> only once.  Only use this if C<sv> is an
+expression with side effects, otherwise use the more efficient C<SvIV>.
 
 =for apidoc Am|NV|SvNV|SV* sv
-Coerce the given SV to a double and return it.  See C<L</SvNVx>> for a version
-which guarantees to evaluate C<sv> only once.
+Coerces the given SV to NV and returns it.  The returned value in many
+circumstances will get stored in C<sv>'s NV slot, but not in all cases.  (Use
+C<L</sv_setnv>> to make sure it does).
+
+See C<L</SvNVx>> for a version which guarantees to evaluate C<sv> only once.
 
 =for apidoc Am|NV|SvNV_nomg|SV* sv
 Like C<SvNV> but doesn't process magic.
 
 =for apidoc Am|NV|SvNVx|SV* sv
-Coerces the given SV to a double and returns it.
-Guarantees to evaluate C<sv> only once.  Only use
-this if C<sv> is an expression with side effects,
-otherwise use the more efficient C<SvNV>.
+Coerces the given SV to NV and returns it.  The returned value in many
+circumstances will get stored in C<sv>'s NV slot, but not in all cases.  (Use
+C<L</sv_setnv>> to make sure it does).
+
+This form guarantees to evaluate C<sv> only once.  Only use this if C<sv> is an
+expression with side effects, otherwise use the more efficient C<SvNV>.
 
 =for apidoc Am|UV|SvUV|SV* sv
-Coerces the given SV to an unsigned integer and returns it.  See C<L</SvUVx>>
-for a version which guarantees to evaluate C<sv> only once.
+Coerces the given SV to UV and returns it.  The returned value in many
+circumstances will get stored in C<sv>'s UV slot, but not in all cases.  (Use
+C<L</sv_setuv>> to make sure it does).
+
+See C<L</SvUVx>> for a version which guarantees to evaluate C<sv> only once.
 
 =for apidoc Am|UV|SvUV_nomg|SV* sv
 Like C<SvUV> but doesn't process magic.
 
 =for apidoc Am|UV|SvUVx|SV* sv
-Coerces the given SV to an unsigned integer and
-returns it.  Guarantees to evaluate C<sv> only once.  Only
-use this if C<sv> is an expression with side effects,
-otherwise use the more efficient C<SvUV>.
+Coerces the given SV to UV and returns it.  The returned value in many
+circumstances will get stored in C<sv>'s UV slot, but not in all cases.  (Use
+C<L</sv_setuv>> to make sure it does).
+
+This form guarantees to evaluate C<sv> only once.  Only use this if C<sv> is an
+expression with side effects, otherwise use the more efficient C<SvUV>.
 
 =for apidoc Am|bool|SvTRUE|SV* sv
 Returns a boolean indicating whether Perl would evaluate the SV as true or