From f99363e23102c1dceb83d066e3b16c4688079634 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 17 Mar 2020 15:05:17 -0400
Subject: [PATCH] Doc: clarify behavior of "anyrange" pseudo-type.

I noticed that we completely failed to document the restriction
that an "anyrange" result type has to be inferred from an "anyrange"
input.  The docs also were less clear than they could be about the
relationship between "anyrange" and "anyarray".

It's been like this all along, so back-patch.
---
 doc/src/sgml/extend.sgml | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index 74130dc51d1..afd2b8f9fcc 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -225,10 +225,12 @@
      <type>anyarray</type> positions must be an array whose elements are
      the same type appearing in the <type>anyelement</type> positions.
      Similarly, if there are positions declared <type>anyrange</type>
-     and others declared <type>anyelement</type>, the actual range type in
-     the <type>anyrange</type> positions must be a range whose subtype is
-     the same type appearing in the <type>anyelement</type> positions.
-     <type>anynonarray</> is treated exactly the same as <type>anyelement</>,
+     and others declared <type>anyelement</type> or <type>anyarray</type>,
+     the actual range type in the <type>anyrange</type> positions must be a
+     range whose subtype is the same type appearing in
+     the <type>anyelement</type> positions and the same as the element type
+     of the <type>anyarray</type> positions.
+     <type>anynonarray</type> is treated exactly the same as <type>anyelement</type>,
      but adds the additional constraint that the actual type must not be
      an array type.
      <type>anyenum</> is treated exactly the same as <type>anyelement</>,
@@ -258,6 +260,17 @@
      will only accept arrays of enum types.
     </para>
 
+    <para>
+     In most cases, the parser can infer the actual data type for a
+     polymorphic result type from arguments that are of a different
+     polymorphic type; for example <type>anyarray</type> can be deduced
+     from <type>anyelement</type> or vice versa.  The exception is that a
+     polymorphic result of type <type>anyrange</type> requires an argument
+     of type <type>anyrange</type>; it cannot be deduced
+     from <type>anyarray</type> or <type>anyelement</type> arguments.  This
+     is because there could be multiple range types with the same subtype.
+    </para>
+
     <para>
      Note that <type>anynonarray</> and <type>anyenum</> do not represent
      separate type variables; they are the same type as