perlapi: Clarify av_pop
authorKarl Williamson <public@khwilliamson.com>
Sat, 12 Jan 2013 15:48:01 +0000 (08:48 -0700)
committerKarl Williamson <public@khwilliamson.com>
Sat, 12 Jan 2013 16:00:07 +0000 (09:00 -0700)
This notes that the caller now has control of a reference count of the
returned SV.

Wording mostly suggested by Paul Evans

av.c

index b251822..475496d 100644 (file)
--- a/av.c
+++ b/av.c
@@ -592,8 +592,9 @@ Perl_av_push(pTHX_ AV *av, SV *val)
 /*
 =for apidoc av_pop
 
-Pops an SV off the end of the array.  Returns C<&PL_sv_undef> if the array
-is empty.
+Removes one SV from the end of the array, reducing its size by one and
+returning the SV (transferring control of one reference count) to the
+caller.  Returns C<&PL_sv_undef> if the array is empty.
 
 Perl equivalent: C<pop(@myarray);>