From 357ea45b5772486395c7fbddccdca22ca1b7c1ae Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 26 May 2005 20:05:03 +0000
Subject: [PATCH] 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 | 50 ++++++++++++++---
doc/src/sgml/ref/comment.sgml | 80 +++++++++++++++++++++-------
doc/src/sgml/ref/drop_function.sgml | 40 ++++++++++++--
doc/src/sgml/ref/grant.sgml | 4 +-
doc/src/sgml/ref/revoke.sgml | 4 +-
5 files changed, 142 insertions(+), 36 deletions(-)
diff --git a/doc/src/sgml/ref/alter_function.sgml b/doc/src/sgml/ref/alter_function.sgml
index 468aa2b2e2e..2f4b901f48e 100644
--- a/doc/src/sgml/ref/alter_function.sgml
+++ b/doc/src/sgml/ref/alter_function.sgml
@@ -1,5 +1,5 @@
<!--
-$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>
diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index 961623c3da3..593df4743c0 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -1,5 +1,5 @@
<!--
-$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>) |
@@ -103,6 +103,64 @@ COMMENT ON
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><replaceable>sourcetype</replaceable></term>
+ <listitem>
+ <para>
+ The name of the source data type of the cast.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <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>
+ 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 class="parameter">argname</replaceable></term>
+
+ <listitem>
+ <para>
+ 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 class="parameter">argtype</replaceable></term>
+
+ <listitem>
+ <para>
+ 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>
@@ -122,24 +180,6 @@ COMMENT ON
</para>
</listitem>
</varlistentry>
-
- <varlistentry>
- <term><replaceable>sourcetype</replaceable></term>
- <listitem>
- <para>
- The name of the source data type of the cast.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <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">text</replaceable></term>
diff --git a/doc/src/sgml/ref/drop_function.sgml b/doc/src/sgml/ref/drop_function.sgml
index 7cc8b7f4da0..85290acff08 100644
--- a/doc/src/sgml/ref/drop_function.sgml
+++ b/doc/src/sgml/ref/drop_function.sgml
@@ -1,5 +1,5 @@
<!--
-$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>
diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index 45f384f4868..c1875abb2fe 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -1,5 +1,5 @@
<!--
-$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 ] }
diff --git a/doc/src/sgml/ref/revoke.sgml b/doc/src/sgml/ref/revoke.sgml
index 5f94537e26e..b7bd2faa8ea 100644
--- a/doc/src/sgml/ref/revoke.sgml
+++ b/doc/src/sgml/ref/revoke.sgml
@@ -1,5 +1,5 @@
<!--
-$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 ]
--
GitLab