PATCH: [perl #120386]: av_len documentation

I think I have incorporated everybody's concerns in this patch.

1 files changed, 8 insertions, 3 deletions

diff --git a/av.c b/av.c
index c08d2c2d3f..0602525a45 100644
--- a/av.c
+++ b/av.c
@@ -760,11 +760,16 @@ The Perl equivalent for this is C<$#myarray>.
 
 (A slightly shorter form is C<av_tindex>.)
 
+=for apidoc av_tindex
+
+Same as L</av_top_index>.
+
 =for apidoc av_len
 
-Same as L</av_top_index>.  Returns the highest index in the array.  Note that the
-return value is +1 what its name implies it returns; and hence differs in
-meaning from what the similarly named L</sv_len> returns.
+Same as L</av_top_index>.  Note that, unlike what the name implies, it returns
+the highest index in the array, so to get the size of the array you need to use
+S<C<av_len(av) + 1>>.  This is unlike L</sv_len>, which returns what you would
+expect.
 
 =cut
 */