newAV_alloc_x - revise wording around size vs key (AvMAX)

av.c

@@ -405,6 +405,9 @@ This is similar to but more efficient than doing:
 
 The zeroflag parameter controls whether the array is NULL initialized.
 
+Note that av_index() takes the desired AvMAX as its key parameter, but
+av_new_alloc() instead takes the desired size (so AvMAX + 1).
+
 =cut
 */
 

av.h

@@ -118,9 +118,23 @@ This is similar to but more efficient than doing:
     AV *av = newAV();
     av_extend(av, key);
 
-Note that these the actual size requested is allocated. This is unlike
-av_extend(), which enforces a minimum size of 3, and always does a +1
-to the requested/minimum size when allocating.
+Note that the actual size requested is allocated. This is unlike
+av_extend(), which takes the maximum desired array index (AvMAX) as its
+"key" parameter, and enforces a minimum value for that of 3.
+
+In other words, the following examples all result in an array that can
+fit four elements (indexes 0 .. 3):
+
+    AV *av = newAV();
+    av_extend(av, 1);
+
+    AV *av = newAV();
+    av_extend(av, 3);
+
+    AV *av = newAV_alloc_x(4);
+
+newAV_alloc_x does not initialize the array with NULL pointers.
+newAV_alloc_xz does do that initialization.
 
 =cut
 */