Re: doc - add missing documentation for "acldefault"

Joe Conway <mail@joeconway.com> writes:
> * I do believe aclitemeq() has utility outside internal purposes.

Our normal policy is that we do not document functions that are meant to
be invoked through operators.  The \df output saying that is sufficient:

# \df+ aclitemeq
                                                                                        List of functions
   Schema   |   Name    | Result data type | Argument data types | Type | Volatility | Parallel |  Owner   | Security |
Accessprivileges | Language | Source code |         Description           

------------+-----------+------------------+---------------------+------+------------+----------+----------+----------+-------------------+----------+-------------+------------------------------
 pg_catalog | aclitemeq | boolean          | aclitem, aclitem    | func | immutable  | safe     | postgres | invoker  |
                 | internal | aclitem_eq  | implementation of = operator 
(1 row)

I would strongly object to ignoring that policy in just one place.

Actually, it appears that most of these functions have associated
operators:

# select oid::regoperator, oprcode from pg_operator where oprright = 'aclitem'::regtype;
          oid          |   oprcode
-----------------------+-------------
 +(aclitem[],aclitem)  | aclinsert
 -(aclitem[],aclitem)  | aclremove
 @>(aclitem[],aclitem) | aclcontains
 =(aclitem,aclitem)    | aclitemeq
 ~(aclitem[],aclitem)  | aclcontains
(5 rows)

So maybe what we really need is a table of operators not functions.
However, I don't object to documenting any function that has its
own pg_description string.

            regards, tom lane