Document that utility commands such as DROP FUNCTION allow argument names

and modes to be included when naming an existing function.

doc/src/sgml/ref/alter_function.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_function.sgml,v 1.6 2005/03/14 00:19:36 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_function.sgml,v 1.7 2005/05/26 20:05:03 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -20,9 +20,12 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-ALTER FUNCTION <replaceable>name</replaceable> ( [ <replaceable class="parameter">type</replaceable> [, ...] ] ) <replaceable class="PARAMETER">action</replaceable> [, ... ] [ RESTRICT ]
-ALTER FUNCTION <replaceable>name</replaceable> ( [ <replaceable class="parameter">type</replaceable> [, ...] ] ) RENAME TO <replaceable>newname</replaceable>
-ALTER FUNCTION <replaceable>name</replaceable> ( [ <replaceable class="parameter">type</replaceable> [, ...] ] ) OWNER TO <replaceable>newowner</replaceable>
+ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] )
+    <replaceable class="PARAMETER">action</replaceable> [, ... ] [ RESTRICT ]
+ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] )
+    RENAME TO <replaceable>newname</replaceable>
+ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] )
+    OWNER TO <replaceable>newowner</replaceable>
 
 where <replaceable class="PARAMETER">action</replaceable> is one of:
 
@@ -55,10 +58,41 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
    </varlistentry>
 
    <varlistentry>
-    <term><replaceable class="parameter">type</replaceable></term>
+    <term><replaceable class="parameter">argmode</replaceable></term>
+
+    <listitem>
+     <para>
+      The mode of an argument: either <literal>IN</>, <literal>OUT</>,
+      or <literal>INOUT</>.  If omitted, the default is <literal>IN</>.
+      Note that <command>ALTER FUNCTION</command> does not actually pay
+      any attention to <literal>OUT</> arguments, since only the input
+      arguments are needed to determine the function's identity.
+      So it is sufficient to list the <literal>IN</> and <literal>INOUT</>
+      arguments.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">argname</replaceable></term>
+
+    <listitem>
+     <para>
+      The name of an argument.
+      Note that <command>ALTER FUNCTION</command> does not actually pay
+      any attention to argument names, since only the argument data
+      types are needed to determine the function's identity.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">argtype</replaceable></term>
+
     <listitem>
      <para>
-      The data type of an argument of the function.
+      The data type(s) of the function's arguments (optionally 
+      schema-qualified), if any.
      </para>
     </listitem>
    </varlistentry>
@@ -116,8 +150,8 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
    </varlistentry>
 
    <varlistentry>
-    <term><literal><optional>EXTERNAL</optional> SECURITY INVOKER</literal></term>
-    <term><literal><optional>EXTERNAL</optional> SECURITY DEFINER</literal></term>
+    <term><literal><optional> EXTERNAL </optional> SECURITY INVOKER</literal></term>
+    <term><literal><optional> EXTERNAL </optional> SECURITY DEFINER</literal></term>
 
     <listitem>
      <para>

doc/src/sgml/ref/comment.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/comment.sgml,v 1.27 2005/03/07 04:30:51 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/comment.sgml,v 1.28 2005/05/26 20:05:03 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -30,7 +30,7 @@ COMMENT ON
   CONVERSION <replaceable class="PARAMETER">object_name</replaceable> |
   DATABASE <replaceable class="PARAMETER">object_name</replaceable> |
   DOMAIN <replaceable class="PARAMETER">object_name</replaceable> |
-  FUNCTION <replaceable class="PARAMETER">func_name</replaceable> (<replaceable class="PARAMETER">arg1_type</replaceable>, <replaceable class="PARAMETER">arg2_type</replaceable>, ...) |
+  FUNCTION <replaceable class="PARAMETER">func_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) |
   INDEX <replaceable class="PARAMETER">object_name</replaceable> |
   LARGE OBJECT <replaceable class="PARAMETER">large_object_oid</replaceable> |
   OPERATOR <replaceable class="PARAMETER">op</replaceable> (<replaceable class="PARAMETER">leftoperand_type</replaceable>, <replaceable class="PARAMETER">rightoperand_type</replaceable>) |
@@ -105,38 +105,78 @@ COMMENT ON
    </varlistentry>
    
    <varlistentry>
-    <term><replaceable class="parameter">large_object_oid</replaceable></term>
+     <term><replaceable>sourcetype</replaceable></term>
      <listitem>
       <para>
-      The OID of the large object.
+       The name of the source data type of the cast.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><literal>PROCEDURAL</literal></term>
+     <term><replaceable>targettype</replaceable></term>
+     <listitem>
+      <para>
+       The name of the target data type of the cast.
+      </para>
+     </listitem>
+    </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">argmode</replaceable></term>
 
     <listitem>
      <para>
-       This is a noise word.
+      The mode of a function argument: either <literal>IN</>, <literal>OUT</>,
+      or <literal>INOUT</>.  If omitted, the default is <literal>IN</>.
+      Note that <command>COMMENT ON FUNCTION</command> does not actually pay
+      any attention to <literal>OUT</> arguments, since only the input
+      arguments are needed to determine the function's identity.
+      So it is sufficient to list the <literal>IN</> and <literal>INOUT</>
+      arguments.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-     <term><replaceable>sourcetype</replaceable></term>
+    <term><replaceable class="parameter">argname</replaceable></term>
+
     <listitem>
      <para>
-       The name of the source data type of the cast.
+      The name of a function argument.
+      Note that <command>COMMENT ON FUNCTION</command> does not actually pay
+      any attention to argument names, since only the argument data
+      types are needed to determine the function's identity.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-     <term><replaceable>targettype</replaceable></term>
+    <term><replaceable class="parameter">argtype</replaceable></term>
+
     <listitem>
      <para>
-       The name of the target data type of the cast.
+      The data type(s) of the function's arguments (optionally 
+      schema-qualified), if any.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">large_object_oid</replaceable></term>
+    <listitem>
+     <para>
+      The OID of the large object.
+     </para>
+    </listitem>
+   </varlistentry>
+
+    <varlistentry>
+     <term><literal>PROCEDURAL</literal></term>
+
+     <listitem>
+      <para>
+       This is a noise word.
       </para>
      </listitem>
     </varlistentry>

doc/src/sgml/ref/drop_function.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_function.sgml,v 1.29 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_function.sgml,v 1.30 2005/05/26 20:05:03 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -20,7 +20,8 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-DROP FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">type</replaceable> [, ...] ] ) [ CASCADE | RESTRICT ]
+DROP FUNCTION <replaceable class="parameter">name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] )
+    [ CASCADE | RESTRICT ]
 </synopsis>
  </refsynopsisdiv>
 
@@ -50,10 +51,41 @@ DROP FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable
    </varlistentry>
 
    <varlistentry>
-    <term><replaceable class="parameter">type</replaceable></term>
+    <term><replaceable class="parameter">argmode</replaceable></term>
+
+    <listitem>
+     <para>
+      The mode of an argument: either <literal>IN</>, <literal>OUT</>,
+      or <literal>INOUT</>.  If omitted, the default is <literal>IN</>.
+      Note that <command>DROP FUNCTION</command> does not actually pay
+      any attention to <literal>OUT</> arguments, since only the input
+      arguments are needed to determine the function's identity.
+      So it is sufficient to list the <literal>IN</> and <literal>INOUT</>
+      arguments.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">argname</replaceable></term>
+
+    <listitem>
+     <para>
+      The name of an argument.
+      Note that <command>DROP FUNCTION</command> does not actually pay
+      any attention to argument names, since only the argument data
+      types are needed to determine the function's identity.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">argtype</replaceable></term>
+
     <listitem>
      <para>
-      The data type of an argument of the function.
+      The data type(s) of the function's arguments (optionally 
+      schema-qualified), if any.
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/grant.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.46 2005/04/28 21:47:09 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.47 2005/05/26 20:05:03 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -30,7 +30,7 @@ GRANT { { CREATE | TEMPORARY | TEMP } [,...] | ALL [ PRIVILEGES ] }
     TO { <replaceable class="PARAMETER">username</replaceable> | GROUP <replaceable class="PARAMETER">groupname</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
 
 GRANT { EXECUTE | ALL [ PRIVILEGES ] }
-    ON FUNCTION <replaceable>funcname</replaceable> ([<replaceable>type</replaceable>, ...]) [, ...]
+    ON FUNCTION <replaceable>funcname</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) [, ...]
     TO { <replaceable class="PARAMETER">username</replaceable> | GROUP <replaceable class="PARAMETER">groupname</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
 
 GRANT { USAGE | ALL [ PRIVILEGES ] }

doc/src/sgml/ref/revoke.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/revoke.sgml,v 1.32 2004/11/05 19:15:52 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/revoke.sgml,v 1.33 2005/05/26 20:05:03 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -35,7 +35,7 @@ REVOKE [ GRANT OPTION FOR ]
 
 REVOKE [ GRANT OPTION FOR ]
     { EXECUTE | ALL [ PRIVILEGES ] }
-    ON FUNCTION <replaceable>funcname</replaceable> ([<replaceable>type</replaceable>, ...]) [, ...]
+    ON FUNCTION <replaceable>funcname</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) [, ...]
     FROM { <replaceable class="PARAMETER">username</replaceable> | GROUP <replaceable class="PARAMETER">groupname</replaceable> | PUBLIC } [, ...]
     [ CASCADE | RESTRICT ]