Doc: improve description of IN and row-constructor comparisons.

IN and NOT IN work fine on records and arrays, so just say that
they accept "expressions" not "scalar expressions".  I think that
that phrasing was meant to say that they don't work on set-returning
expressions, but that's not the common meaning of "scalar".

Revise the description of row-constructor comparisons to make it
perhaps a bit less confusing.  (This partially reverts some
dubious wording changes made by commit f56651519.)

Per gripe from Ilya Nenashev.  Back-patch to supported branches.
In HEAD and v16, also drop a NOTE about pre-8.2 behavior, which
is hopefully no longer of interest to anybody.

Discussion: https://postgr.es/m/168968062460.632.14303906825812821399@wrigleys.postgresql.org

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index ec88ca18886157867a7551f94c4b6866d1141453..3f4a841bee8f6b40ecabc403502cfa0465d0de37 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -21185,7 +21185,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
 
   
    The right-hand side is a parenthesized list
-   of scalar expressions.  The result is true if the left-hand expression's
+   of expressions.  The result is true if the left-hand expression's
    result is equal to any of the right-hand expressions.  This is a shorthand
    notation for
 
@@ -21216,7 +21216,7 @@ OR
 
   
    The right-hand side is a parenthesized list
-   of scalar expressions.  The result is true if the left-hand expression's
+   of expressions.  The result is true if the left-hand expression's
    result is unequal to all of the right-hand expressions.  This is a shorthand
    notation for
 
@@ -21327,26 +21327,24 @@ AND
   
    Each side is a row constructor,
    as described in .
-   The two row values must have the same number of fields.
-   Each side is evaluated and they are compared row-wise.  Row constructor
-   comparisons are allowed when the operator is
+   The two row constructors must have the same number of fields.
+   The given operator is applied to each pair
+   of corresponding fields.  (Since the fields could be of different
+   types, this means that a different specific operator could be selected
+   for each pair.)
+   All the selected operators must be members of some B-tree operator
+   class, or be the negator of an = member of a B-tree
+   operator class, meaning that row constructor comparison is only
+   possible when the operator is
    =,
    <>,
    <,
    <=,
-   > or
-   >=.
-   Every row element must be of a type which has a default B-tree operator
-   class or the attempted comparison may generate an error.
+   >, or
+   >=,
+   or has semantics similar to one of these.
   
 
-  
-   
-    Errors related to the number or types of elements might not occur if
-    the comparison is resolved using earlier columns.
-   
-  
-
   
    The = and <> cases work slightly differently
    from the others.  Two rows are considered