1 files changed, 63 insertions, 3 deletions

diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml
index e27512ff391..c421fd21e9d 100644
--- a/doc/src/sgml/ref/create_operator.sgml
+++ b/doc/src/sgml/ref/create_operator.sgml
@@ -104,7 +104,7 @@ CREATE OPERATOR <replaceable>name</replaceable> (
   </para>
 
   <para>
-   The other clauses specify optional operator optimization clauses.
+   The other clauses specify optional operator optimization attributes.
    Their meaning is detailed in <xref linkend="xoper-optimization"/>.
   </para>
 
@@ -112,7 +112,7 @@ CREATE OPERATOR <replaceable>name</replaceable> (
    To be able to create an operator, you must have <literal>USAGE</literal>
    privilege on the argument types and the return type, as well
    as <literal>EXECUTE</literal> privilege on the underlying function.  If a
-   commutator or negator operator is specified, you must own these operators.
+   commutator or negator operator is specified, you must own those operators.
   </para>
  </refsect1>
 
@@ -231,7 +231,67 @@ COMMUTATOR = OPERATOR(myschema.===) ,
   <title>Notes</title>
 
   <para>
-   Refer to <xref linkend="xoper"/> for further information.
+   Refer to <xref linkend="xoper"/> and <xref linkend="xoper-optimization"/>
+   for further information.
+  </para>
+
+  <para>
+   When you are defining a self-commutative operator, you just do it.
+   When you are defining a pair of commutative operators, things are
+   a little trickier: how can the first one to be defined refer to the
+   other one, which you haven't defined yet?  There are three solutions
+   to this problem:
+
+   <itemizedlist>
+    <listitem>
+     <para>
+      One way is to omit the <literal>COMMUTATOR</literal> clause in the
+      first operator that you define, and then provide one in the second
+      operator's definition.  Since <productname>PostgreSQL</productname>
+      knows that commutative operators come in pairs, when it sees the
+      second definition it will automatically go back and fill in the
+      missing <literal>COMMUTATOR</literal> clause in the first
+      definition.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      Another, more straightforward way is just to
+      include <literal>COMMUTATOR</literal> clauses in both definitions.
+      When <productname>PostgreSQL</productname> processes the first
+      definition and realizes that <literal>COMMUTATOR</literal> refers to
+      a nonexistent operator, the system will make a dummy entry for that
+      operator in the system catalog.  This dummy entry will have valid
+      data only for the operator name, left and right operand types, and
+      owner, since that's all that <productname>PostgreSQL</productname>
+      can deduce at this point.  The first operator's catalog entry will
+      link to this dummy entry.  Later, when you define the second
+      operator, the system updates the dummy entry with the additional
+      information from the second definition.  If you try to use the dummy
+      operator before it's been filled in, you'll just get an error
+      message.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      Alternatively, both operators can be defined
+      without <literal>COMMUTATOR</literal> clauses
+      and then <command>ALTER OPERATOR</command> can be used to set their
+      commutator links.  It's sufficient to <command>ALTER</command>
+      either one of the pair.
+     </para>
+    </listitem>
+   </itemizedlist>
+
+   In all three cases, you must own both operators in order to mark
+   them as commutators.
+  </para>
+
+  <para>
+   Pairs of negator operators can be defined using the same methods
+   as for commutator pairs.
   </para>
 
   <para>