Make argument names of pg_get_object_address consistent, and fix docs.

pg_get_object_address and pg_identify_object_as_address are supposed
to be inverses, but they disagreed as to the names of the arguments
representing the textual form of an object address.  Moreover, the
documented argument names didn't agree with reality at all, either
for these functions or pg_identify_object.

In HEAD and v11, I think we can get away with renaming the input
arguments of pg_get_object_address to match the outputs of
pg_identify_object_as_address.  In theory that might break queries
using named-argument notation to call pg_get_object_address, but
it seems really unlikely that anybody is doing that, or that they'd
have much trouble adjusting if they were.  In older branches, we'll
just live with the lack of consistency.

Aside from fixing the documentation of these functions to match reality,
I couldn't resist the temptation to do some copy-editing.

Per complaint from Jean-Pierre Pelletier.  Back-patch to 9.5 where these
functions were introduced.  (Before v11, this is a documentation change
only.)

Discussion: https://postgr.es/m/CANGqjDnWH8wsTY_GzDUxbt4i=y-85SJreZin4Hm8uOqv1vzRQA@mail.gmail.com

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 9f2b1d49237796cff728fd196cf60e6e87643f7c..4f4083711b3f049bc92a94d74e43608cece99079 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17015,24 +17015,24 @@ SELECT collation for ('foo' COLLATE "de_DE");
 
      
       
-       pg_describe_object(catalog_id, object_id, object_sub_id>)
+       pg_describe_object(classid oid, objid oid, objsubid integer>)
        text
        get description of a database object
       
       
-       pg_identify_object(catalog_id oid, object_id oid, object_sub_id integer>)
-       type> text, schema text, name text, identity text>
+       pg_identify_object(classid oid, objid oid, objsubid integer>)
+       typeparameter> text, schema text, name text, identity text>
        get identity of a database object
       
       
-       pg_identify_object_as_address(catalog_id oid, object_id oid, object_sub_id integer>)
-       type> text, name text[], args text[]>
+       pg_identify_object_as_address(classid oid, objid oid, objsubid integer>)
+       typeparameter> text, object_names text[], object_args text[]>
        get external representation of a database object's address
       
       
-       pg_get_object_address(type text>, name text[], args text[]>)
-       catalog_id oid, object_id oid, object_sub_id int32>
-       get address of a database object, from its external representation
+       pg_get_object_address(type texttype>, name text[], args text[]>)
+       classid oid, objid oid, objsubid integer>
+       get address of a database object from its external representation
       
      
     
@@ -17040,7 +17040,9 @@ SELECT collation for ('foo' COLLATE "de_DE");
 
   
    pg_describe_object returns a textual description of a database
-   object specified by catalog OID, object OID and a (possibly zero) sub-object ID.
+   object specified by catalog OID, object OID, and sub-object ID (such as
+   a column number within a table; the sub-object ID is zero when referring
+   to a whole object).
    This description is intended to be human-readable, and might be translated,
    depending on server configuration.
    This is useful to determine the identity of an object as stored in the
@@ -17049,30 +17051,31 @@ SELECT collation for ('foo' COLLATE "de_DE");
 
   
    pg_identify_object returns a row containing enough information
-   to uniquely identify the database object specified by catalog OID, object OID and a
-   (possibly zero) sub-object ID.  This information is intended to be machine-readable,
+   to uniquely identify the database object specified by catalog OID, object OID and
+   sub-object ID.  This information is intended to be machine-readable,
    and is never translated.
-   type identifies the type of database object;
-   schema is the schema name that the object belongs in, or
-   NULL for object types that do not belong to schemas;
-   name> is the name of the object, quoted if necessary, only
-   present if it can be used (alongside schema name, if pertinent) as a unique
-   identifier of the object, otherwise NULL>;
-   identity> is the complete object identity, with the precise format
-   depending on object type, and each part within the format being
-   schema-qualified and quoted as necessary.
+   typeparameter> identifies the type of database object;
+   schemaparameter> is the schema name that the object belongs in, or
+   NULLliteral> for object types that do not belong to schemas;
+   nameparameter> is the name of the object, quoted if necessary,
+   if the name (along with schema name, if pertinent) is sufficient to
+   uniquely identify the object, otherwise NULL>;
+   identityparameter> is the complete object identity, with the
+   precise format depending on object type, and each name within the format
+   being schema-qualified and quoted as necessary.
   
 
   
    pg_identify_object_as_address returns a row containing
    enough information to uniquely identify the database object specified by
-   catalog OID, object OID and a (possibly zero) sub-object ID.  The returned
+   catalog OID, object OID and sub-object ID.  The returned
    information is independent of the current server, that is, it could be used
    to identify an identically named object in another server.
-   type identifies the type of database object;
-   name and args are text arrays that together
-   form a reference to the object.  These three columns can be passed to
-   pg_get_object_address to obtain the internal address
+   type identifies the type of database object;
+   object_names and object_args
+   are text arrays that together form a reference to the object.
+   These three values can be passed to
+   pg_get_object_address to obtain the internal address
    of the object.
    This function is the inverse of pg_get_object_address.
   
@@ -17081,13 +17084,13 @@ SELECT collation for ('foo' COLLATE "de_DE");
    pg_get_object_address returns a row containing enough
    information to uniquely identify the database object specified by its
    type and object name and argument arrays.  The returned values are the
-   ones that would be used in system catalogs such as pg_depend
+   ones that would be used in system catalogs such as pg_dependstructname>
    and can be passed to other system functions such as
-   pg_identify_object> or pg_describe_object>.
-   catalog_id> is the OID of the system catalog containing the
+   pg_identify_objectfunction> or pg_describe_object>.
+   classid> is the OID of the system catalog containing the
    object;
-   object_id> is the OID of the object itself, and
-   object_sub_id is the object sub-ID, or zero if none.
+   objid> is the OID of the object itself, and
+   objsubid is the sub-object ID, or zero if none.
    This function is the inverse of pg_identify_object_as_address.
   
 
@@ -19782,23 +19785,23 @@ FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger();
       
        
         classid
-        Oid
+        oid
         OID of catalog the object belongs in
        
        
         objid
-        Oid
-        OID of the object in the catalog
+        oid
+        OID of the object itself
        
        
         objsubid
         integer
-        Object sub-id (e.g. attribute number for columns)
+        Sub-object ID (e.g. attribute number for a column)
        
        
         command_tag
         text
-        command tag
+        Command tag
        
        
         object_type
@@ -19817,14 +19820,14 @@ FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger();
         object_identity
         text
         
-         Text rendering of the object identity, schema-qualified. Each and every
-         identifier present in the identity is quoted if necessary.
+         Text rendering of the object identity, schema-qualified. Each
+         identifier included in the identity is quoted if necessary.
         
        
        
         in_extension
         bool
-        whether the command is part of an extension script
+        True if the command is part of an extension script
        
        
         command
@@ -19869,29 +19872,29 @@ FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger();
       
        
         classid
-        Oid
+        oid
         OID of catalog the object belonged in
        
        
         objid
-        Oid
-        OID the object had within the catalog
+        oid
+        OID of the object itself
        
        
         objsubid
-        int32
-        Object sub-id (e.g. attribute number for columns)
+        integer
+        Sub-object ID (e.g. attribute number for a column)
        
        
         original
         bool
-        Flag used to identify the root object(s) of the deletion
+        True if this was one of the root object(s) of the deletion
        
        
         normal
         bool
         
-         Flag indicating that there's a normal dependency relationship
+         True if there was a normal dependency relationship
          in the dependency graph leading to this object
         
        
@@ -19899,7 +19902,7 @@ FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger();
         is_temporary
         bool
         
-         Flag indicating that the object was a temporary object.
+         True if this was a temporary object
         
        
        
@@ -19928,8 +19931,8 @@ FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger();
         object_identity
         text
         
-         Text rendering of the object identity, schema-qualified. Each and every
-         identifier present in the identity is quoted if necessary.
+         Text rendering of the object identity, schema-qualified. Each
+         identifier included in the identity is quoted if necessary.
         
        
        
@@ -19937,17 +19940,17 @@ FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger();
         text[]
         
          An array that, together with object_type and
-         address_args,
-         can be used by the pg_get_object_address() to
+         address_args, can be used by
+         the pg_get_object_address() function to
          recreate the object address in a remote server containing an
-         identically named object of the same kind.
+         identically named object of the same kind
         
        
        
         address_args
         text[]
         
-         Complement for address_names above.
+         Complement for address_names