Mark factorial operator, and postfix operators in general, as deprecated.

tglsfdc · tglsfdc · commit 1f38d3851190 · 2020-08-30T16:03:19.000-04:00
Back-patch key parts of 4c5cf54 and 6ca547c into stable branches. I didn't touch pg_description entries here, so it's purely a docs change; and I didn't fool with any examples either. The main point is so that anyone who's wondering if factorial() exists in the stable branches will be reassured. Mark Dilger and John Naylor, with some adjustments by me Discussion: https://postgr.es/m/BE2DF53D-251A-4E26-972F-930E523580E9@enterprisedb.com
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
@@ -666,14 +666,16 @@
 
       <row>
        <entry> <literal>!</literal> </entry>
-       <entry>factorial</entry>
+       <entry>factorial
+        (deprecated, use <function>factorial()</function> instead)</entry>
        <entry><literal>5 !</literal></entry>
        <entry><literal>120</literal></entry>
       </row>
 
       <row>
        <entry> <literal>!!</literal> </entry>
-       <entry>factorial (prefix operator)</entry>
+       <entry>factorial as a prefix operator
+        (deprecated, use <function>factorial()</function> instead)</entry>
        <entry><literal>!! 5</literal></entry>
        <entry><literal>120</literal></entry>
       </row>
@@ -856,6 +858,19 @@
        <entry><literal>2.71828182845905</literal></entry>
       </row>
 
+      <row>
+       <entry>
+        <indexterm>
+         <primary>factorial</primary>
+        </indexterm>
+        <literal><function>factorial(<type>bigint</type>)</function></literal>
+       </entry>
+       <entry><type>numeric</type></entry>
+       <entry>factorial</entry>
+       <entry><literal>factorial(5)</literal></entry>
+       <entry><literal>120</literal></entry>
+      </row>
+
       <row>
        <entry>
         <indexterm>
diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml
@@ -87,11 +87,18 @@ CREATE OPERATOR <replaceable>name</replaceable> (
 
   <para>
    At least one of <literal>LEFTARG</> and <literal>RIGHTARG</> must be defined.  For
-   binary operators, both must be defined. For right  unary
+   binary operators, both must be defined. For right unary
    operators, only <literal>LEFTARG</> should be defined, while for left
    unary operators only <literal>RIGHTARG</> should be defined.
   </para>
 
+  <note>
+   <para>
+    Right unary, also called postfix, operators are deprecated and will be
+    removed in <productname>PostgreSQL</productname> version 14.
+   </para>
+  </note>
+
   <para>
    The <replaceable class="parameter">function_name</replaceable>
    procedure must have been previously defined using <command>CREATE
