3 files changed, 32 insertions, 6 deletions
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 90a3460a712..baf81ee0404 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -12035,7 +12035,7 @@ NULL baz</literallayout>(3 rows)</entry>
        <function>array_agg(<replaceable class="parameter">expression</replaceable>)</function>
       </entry>
       <entry>
-       any
+       any non-array type
       </entry>
       <entry>
        array of the argument type
@@ -12045,6 +12045,21 @@ NULL baz</literallayout>(3 rows)</entry>
 
      <row>
       <entry>
+       <function>array_agg(<replaceable class="parameter">expression</replaceable>)</function>
+      </entry>
+      <entry>
+       any array type
+      </entry>
+      <entry>
+       same as argument data type
+      </entry>
+      <entry>input arrays concatenated into array of one higher dimension
+       (inputs must all have same dimensionality,
+        and cannot be empty or NULL)</entry>
+     </row>
+
+     <row>
+      <entry>
        <indexterm>
         <primary>average</primary>
        </indexterm>
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 399ae070759..6f8b7e8b28e 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -2239,11 +2239,22 @@ SELECT ARRAY(SELECT oid FROM pg_proc WHERE proname LIKE 'bytea%');
 -----------------------------------------------------------------------
  {2011,1954,1948,1952,1951,1244,1950,2005,1949,1953,2006,31,2412,2413}
 (1 row)
+
+SELECT ARRAY(SELECT ARRAY[i, i*2] FROM generate_series(1,5) AS a(i));
+              array
+----------------------------------
+ {{1,2},{2,4},{3,6},{4,8},{5,10}}
+(1 row)
 </programlisting>
-   The subquery must return a single column. The resulting
+   The subquery must return a single column.
+   If the subquery's output column is of a non-array type, the resulting
    one-dimensional array will have an element for each row in the
    subquery result, with an element type matching that of the
    subquery's output column.
+   If the subquery's output column is of an array type, the result will be
+   an array of the same type but one higher dimension; in this case all
+   the subquery rows must yield arrays of identical dimensionality, else
+   the result would not be rectangular.
   </para>
 
   <para>
diff --git a/doc/src/sgml/xaggr.sgml b/doc/src/sgml/xaggr.sgml
index cc8ec64f235..ef7cff48794 100644
--- a/doc/src/sgml/xaggr.sgml
+++ b/doc/src/sgml/xaggr.sgml
@@ -359,12 +359,12 @@ SELECT attrelid::regclass, array_accum(atttypid::regtype)
    aggregate <function>array_agg</> is equivalent to
 
 <programlisting>
-CREATE FUNCTION array_agg_transfn(internal, anyelement)
+CREATE FUNCTION array_agg_transfn(internal, anynonarray)
   RETURNS internal ...;
-CREATE FUNCTION array_agg_finalfn(internal, anyelement)
+CREATE FUNCTION array_agg_finalfn(internal, anynonarray)
   RETURNS anyarray ...;
 
-CREATE AGGREGATE array_agg (anyelement)
+CREATE AGGREGATE array_agg (anynonarray)
 (
     sfunc = array_agg_transfn,
     stype = internal,
@@ -376,7 +376,7 @@ CREATE AGGREGATE array_agg (anyelement)
    Here, the <literal>finalfunc_extra</> option specifies that the final
    function receives, in addition to the state value, extra dummy
    argument(s) corresponding to the aggregate's input argument(s).
-   The extra <type>anyelement</> argument allows the declaration
+   The extra <type>anynonarray</> argument allows the declaration
    of <function>array_agg_finalfn</> to be valid.
   </para>