0003-Document-about-COMMENT-ON-USER-MAPPING.patch

From f672ce5d77d60f0422a6eae6c7db56e00a52eaec Mon Sep 17 00:00:00 2001
From: Shigeru Hanada <hanada@metrosystems.co.jp>
Date: Mon, 4 Apr 2011 19:25:22 +0900
Subject: [PATCH 3/5] Document about COMMENT ON USER MAPPING.

---
 doc/src/sgml/ref/comment.sgml |   30 ++++++++++++++++++++++++++++++
 doc/src/sgml/ref/grant.sgml   |    2 +-
 2 files changed, 31 insertions(+), 1 deletions(-)

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index 1cdc49f..c03691a 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -54,6 +54,7 @@ COMMENT ON
   TEXT SEARCH TEMPLATE <replaceable class="PARAMETER">object_name</replaceable> |
   TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
   TYPE <replaceable class="PARAMETER">object_name</replaceable> |
+  USER MAPPING FOR { <replaceable class="PARAMETER">user_name</replaceable> | USER | CURRENT_USER | PUBLIC } SERVER <replaceable class="PARAMETER">server_name</replaceable> |
   VIEW <replaceable class="PARAMETER">object_name</replaceable>
 } IS '<replaceable class="PARAMETER">text</replaceable>'
 </synopsis>
@@ -78,6 +79,10 @@ COMMENT ON
    Roles don't have owners, so the rule for <literal>COMMENT ON ROLE</> is
    that you must be superuser to comment on a superuser role, or have the
    <literal>CREATEROLE</> privilege to comment on non-superuser roles.
+   User mappings don't have owners, so the rule for <literal>COMMENT ON USER
+   MAPPING</> is that the owner of a foreign server can comment on user
+   mappings for the server for any user.  In adittion, user who is granted
+   USAGE privilege on the SERVER can set the comment on his own mapping.
    Of course, a superuser can comment on anything.
   </para>
 
@@ -213,6 +218,30 @@ COMMENT ON
     </varlistentry>
 
    <varlistentry>
+    <term><replaceable>user_name</replaceable></term>
+    <term><literal>USER</literal></term>
+    <term><literal>CURRENT_USER</literal></term>
+    <term><literal>PUBLIC</literal></term>
+    <listitem>
+     <para>
+      The name of the user of the target user mapping.
+      <literal>CURRENT_USER</literal> and <literal>USER</literal> match the
+      name of the current user.  <literal>PUBLIC</literal> is used to match all
+      present and future user names in the system.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable>server_name</replaceable></term>
+    <listitem>
+     <para>
+      The name of the server of the target user mapping.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
     <term><replaceable class="parameter">text</replaceable></term>
     <listitem>
      <para>
@@ -288,6 +317,7 @@ COMMENT ON TEXT SEARCH PARSER my_parser IS 'Splits text into words';
 COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Snowball stemmer';
 COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
 COMMENT ON TYPE complex IS 'Complex number data type';
+COMMENT ON USER MAPPING FOR PUBLIC SERVER my_server IS 'Default mapping';
 COMMENT ON VIEW my_view IS 'View of departmental costs';
 </programlisting>
   </para>
diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index 72ecc45..6a934d6 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -340,7 +340,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
       </para>
       <para>
        For servers, this privilege enables the grantee to create,
-       alter, and drop his own user's user mappings associated with
+       alter, drop and comment his own user's user mappings associated with
        that server.  Also, it enables the grantee to query the options
        of the server and associated user mappings.
       </para>
-- 
1.7.3