newAV_alloc_x - further revise documentation, add assertion

av.c

@@ -406,7 +406,8 @@ 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).
+av_new_alloc() instead takes the desired size (so AvMAX + 1). This
+size must be at least 1.
 
 =cut
 */
@@ -417,8 +418,9 @@ Perl_av_new_alloc(pTHX_ SSize_t size, bool zeroflag)
     AV * const av = newAV();
     SV** ary;
     PERL_ARGS_ASSERT_AV_NEW_ALLOC;
+    assert(size > 1);
 
-    Newx(ary, size, SV*);
+    Newx(ary, size, SV*); /* Newx performs the memwrap check */
     AvALLOC(av) = ary;
     AvARRAY(av) = ary;
     AvMAX(av) = size - 1;

av.h

@@ -111,7 +111,7 @@ Perl equivalent: C<my @array;>.
 /*
 =for apidoc newAV_alloc_x
 
-Similar to newAV(), but the SV* array is also allocated.
+Similar to newAV(), but a SV* array is also allocated.
 
 This is similar to but more efficient than doing:
 
@@ -133,14 +133,20 @@ fit four elements (indexes 0 .. 3):
 
     AV *av = newAV_alloc_x(4);
 
+Whereas this will result in an array that can only fit one element:
+
+    AV *av = newAV_alloc_x(1);
+
 newAV_alloc_x does not initialize the array with NULL pointers.
 newAV_alloc_xz does do that initialization.
 
+These macros MUST NOT be called with a size less than 1.
+
 =cut
 */
 
-#define newAV_alloc_x(key)  av_new_alloc(key,0)
-#define newAV_alloc_xz(key) av_new_alloc(key,1)
+#define newAV_alloc_x(size)  av_new_alloc(size,0)
+#define newAV_alloc_xz(size) av_new_alloc(size,1)
 
 /*
  * ex: set ts=8 sts=4 sw=4 et: