Doc: improve documentation for UNNEST().

Per a user question, spell out that UNNEST() returns array elements
in storage order; also provide an example to clarify the behavior for
multi-dimensional arrays.

While here, also clarify the SELECT reference page's description of
WITH ORDINALITY.  These details were already given in 7.2.1.4, but
a reference page should not omit details.

Back-patch to v13; there's not room in the table in older versions.

Discussion: https://postgr.es/m/FF1FB31F-0507-4F18-9559-2DE6E07E3B43@gmail.com

2 files changed, 27 insertions, 9 deletions

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index aa99665e2eb..4342c8e74fd 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17905,7 +17905,8 @@ SELECT NULLIF(value, '(none)') ...
         <returnvalue>setof anyelement</returnvalue>
        </para>
        <para>
-        Expands an array to a set of rows.
+        Expands an array into a set of rows.
+        The array's elements are read out in storage order.
        </para>
        <para>
         <literal>unnest(ARRAY[1,2])</literal>
@@ -17914,6 +17915,16 @@ SELECT NULLIF(value, '(none)') ...
  1
  2
 </programlisting>
+       </para>
+       <para>
+        <literal>unnest(ARRAY[['foo','bar'],['baz','quux']])</literal>
+        <returnvalue></returnvalue>
+<programlisting>
+ foo
+ bar
+ baz
+ quux
+</programlisting>
        </para></entry>
       </row>
 
@@ -17923,10 +17934,10 @@ SELECT NULLIF(value, '(none)') ...
         <returnvalue>setof anyelement, anyelement [, ... ]</returnvalue>
        </para>
        <para>
-        Expands multiple arrays (possibly of different data types) to a set of
+        Expands multiple arrays (possibly of different data types) into a set of
         rows.  If the arrays are not all the same length then the shorter ones
-        are padded with <literal>NULL</literal>s.  This is only allowed in a
-        query's FROM clause; see <xref linkend="queries-tablefunctions"/>.
+        are padded with <literal>NULL</literal>s.  This form is only allowed
+        in a query's FROM clause; see <xref linkend="queries-tablefunctions"/>.
        </para>
        <para>
         <literal>select * from unnest(ARRAY[1,2], ARRAY['foo','bar','baz']) as x(a,b)</literal>
diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index 6757033e096..c48ff6bc7e8 100644
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -476,9 +476,17 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
         result sets, but any function can be used.)  This acts as
         though the function's output were created as a temporary table for the
         duration of this single <command>SELECT</command> command.
-        When the optional <command>WITH ORDINALITY</command> clause is
-        added to the function call, a new column is appended after
-        all the function's output columns with numbering for each row.
+        If the function's result type is composite (including the case of a
+        function with multiple <literal>OUT</literal> parameters), each
+        attribute becomes a separate column in the implicit table.
+       </para>
+
+       <para>
+        When the optional <command>WITH ORDINALITY</command> clause is added
+        to the function call, an additional column of type <type>bigint</type>
+        will be appended to the function's result column(s).  This column
+        numbers the rows of the function's result set, starting from 1.
+        By default, this column is named <literal>ordinality</literal>.
        </para>
 
        <para>
@@ -486,8 +494,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
         If an alias is written, a column
         alias list can also be written to provide substitute names for
         one or more attributes of the function's composite return
-        type, including the column added by <literal>ORDINALITY</literal>
-        if present.
+        type, including the ordinality column if present.
        </para>
 
        <para>