perlapi: Clarify av_pop

This notes that the caller now has control of a reference count of the
returned SV.

Wording mostly suggested by Paul Evans

diff --git a/av.c b/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);>