Code review for protransform patches.

Fix loss of previous expression-simplification work when a transform
function fires: we must not simply revert to untransformed input tree.
Instead build a dummy FuncExpr node to pass to the transform function.
This has the additional advantage of providing a simpler, more uniform
API for transform functions.

Move documentation to a somewhat less buried spot, relocate some
poorly-placed code, be more wary of null constants and invalid typmod
values, add an opr_sanity check on protransform function signatures,
and some other minor cosmetic adjustments.

Note: although this patch touches pg_proc.h, no need for catversion
bump, because the changes are cosmetic and don't actually change the
intended catalog contents.

doc/src/sgml/catalogs.sgml

@@ -4398,7 +4398,8 @@
       <entry><structfield>protransform</structfield></entry>
       <entry><type>regproc</type></entry>
       <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry>Calls to function can be simplified by this other function</entry>
+      <entry>Calls to this function can be simplified by this other function
+       (see <xref linkend="xfunc-transform-functions">)</entry>
      </row>
 
      <row>

doc/src/sgml/xfunc.sgml

@@ -3177,6 +3177,40 @@ CREATE FUNCTION make_array(anyelement) RETURNS anyarray
     </para>
    </sect2>
 
+   <sect2 id="xfunc-transform-functions">
+    <title>Transform Functions</title>
+
+    <para>
+     Some function calls can be simplified during planning based on
+     properties specific to the function.  For example,
+     <literal>int4mul(n, 1)</> could be simplified to just <literal>n</>.
+     To define such function-specific optimizations, write a
+     <firstterm>transform function</> and place its OID in the
+     <structfield>protransform</> field of the primary function's
+     <structname>pg_proc</> entry.  The transform function must have the SQL
+     signature <literal>protransform(internal) RETURNS internal</>.  The
+     argument, actually <type>FuncExpr *</>, is a dummy node representing a
+     call to the primary function.  If the transform function's study of the
+     expression tree proves that a simplified expression tree can substitute
+     for all possible concrete calls represented thereby, build and return
+     that simplified expression.  Otherwise, return a <literal>NULL</>
+     pointer (<emphasis>not</> a SQL null).
+    </para>
+
+    <para>
+     We make no guarantee that <productname>PostgreSQL</> will never call the
+     primary function in cases that the transform function could simplify.
+     Ensure rigorous equivalence between the simplified expression and an
+     actual call to the primary function.
+    </para>
+
+    <para>
+     Currently, this facility is not exposed to users at the SQL level
+     because of security concerns, so it is only practical to use for
+     optimizing built-in functions.
+    </para>
+   </sect2>
+
    <sect2>
     <title>Shared Memory and LWLocks</title>