Clarify documentation about "peer" rows in window functions

Peer rows are matching rows when ORDER BY is specified.

Report by [email protected], David G Johnston

3 files changed, 8 insertions, 6 deletions

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index daa56e99789..e50408cb977 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -13050,7 +13050,8 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab;
    <firstterm>Window functions</firstterm> provide the ability to perform
    calculations across sets of rows that are related to the current query
    row.  See <xref linkend="tutorial-window"> for an introduction to this
-   feature.
+   feature, and <xref linkend="syntax-window-functions"> for syntax
+   details.
   </para>
 
   <para>
diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index b69b63494b8..940d1aa5c0d 100644
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -792,8 +792,9 @@ UNBOUNDED FOLLOWING
     The default framing option is <literal>RANGE UNBOUNDED PRECEDING</>,
     which is the same as <literal>RANGE BETWEEN UNBOUNDED PRECEDING AND
     CURRENT ROW</>; it sets the frame to be all rows from the partition start
-    up through the current row's last peer in the <literal>ORDER BY</>
-    ordering (which means all rows if there is no <literal>ORDER BY</>).
+    up through the current row's last peer (a row that <literal>ORDER
+    BY</> considers equivalent to the current row, or all rows if there
+    is no <literal>ORDER BY</>).
     In general, <literal>UNBOUNDED PRECEDING</> means that the frame
     starts with the first row of the partition, and similarly
     <literal>UNBOUNDED FOLLOWING</> means that the frame ends with the last
@@ -817,7 +818,7 @@ UNBOUNDED FOLLOWING
     results if the <literal>ORDER BY</> ordering does not order the rows
     uniquely.  The <literal>RANGE</> options are designed to ensure that
     rows that are peers in the <literal>ORDER BY</> ordering are treated
-    alike; any two peer rows will be both in or both not in the frame.
+    alike; all peer rows will be in the same frame.
    </para>
 
    <para>
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 434a8941577..2f0680fd0bc 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1877,7 +1877,7 @@ UNBOUNDED FOLLOWING
     first <firstterm>peer</> row (a row that <literal>ORDER BY</> considers
     equivalent to the current row), while a <replaceable>frame_end</> of
     <literal>CURRENT ROW</> means the frame ends with the last equivalent
-    peer.  In <literal>ROWS</> mode, <literal>CURRENT ROW</> simply means
+    <literal>ORDER BY</> peer.  In <literal>ROWS</> mode, <literal>CURRENT ROW</> simply means
     the current row.
    </para>
 
@@ -1897,7 +1897,7 @@ UNBOUNDED FOLLOWING
     which is the same as <literal>RANGE BETWEEN UNBOUNDED PRECEDING AND
     CURRENT ROW</>.  With <literal>ORDER BY</>, this sets the frame to be
     all rows from the partition start up through the current row's last
-    peer.  Without <literal>ORDER BY</>, all rows of the partition are
+    <literal>ORDER BY</> peer.  Without <literal>ORDER BY</>, all rows of the partition are
     included in the window frame, since all rows become peers of the current
     row.
    </para>