+=for comment
+'form' above and below is because otherwise have two =items with the same name,
+can't link to them.
+
+This does nothing beyond creating the whole-array data structure.
+The Perl equivalent is approximately S<C<my @array;>>
+
+This is useful when the minimum size of the array could be zero (perhaps there
+are likely code paths that will entirely skip using it).
+
+If the array does get used, the pointers data structure will need to be
+allocated at that time. This will end up being done by L</av_extend>>,
+either explicitly:
+
+ av_extend(av, len);
+
+or implicitly when the first element is stored:
+
+ (void)av_store(av, 0, sv);
+
+Unused array elements are typically initialized by C<av_extend>.
+
+=item C<newAV_alloc_x> form
+
+This effectively does a C<newAV> followed by also allocating (uninitialized)
+space for the pointers array. This is used when you know ahead of time the
+likely minimum size of the array. It is more efficient to do this than doing a
+plain C<newAV> followed by an C<av_extend>.
+
+Of course the array can be extended later should it become necessary.
+
+C<size> must be at least 1.
+
+=item C<newAV_alloc_xz> form
+
+This is C<newAV_alloc_x>, but initializes each pointer in it to NULL. This
+gives added safety to guard against them being read before being set.
+
+C<size> must be at least 1.
+
+=back
+
+The following examples all result in an array that can fit four elements
+(indexes 0 .. 3):
+
+ AV *av = newAV();
+ av_extend(av, 3);
+
+ AV *av = newAV_alloc_x(4);
+
+ AV *av = newAV_alloc_xz(4);
+
+In contrast, the following examples allocate an array that is only guaranteed
+to fit one element without extending:
+
+ AV *av = newAV_alloc_x(1);
+ AV *av = newAV_alloc_xz(1);