Re: doc - add missing documentation for "acldefault"

From: Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr>
To: Pavel Luzanov <p(dot)luzanov(at)postgrespro(dot)ru>
Cc: PostgreSQL Developers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: Re: doc - add missing documentation for "acldefault"
Date: 2018-08-03 09:17:05
Message-ID: alpine.DEB.2.21.1808031106420.8068@lancre
Views: Raw Message | Whole Thread | Download mbox
Thread:
Lists: pgsql-hackers


Hello,

>> However, the point of having hidden and/or undocumented functions fails me:
>> they are hard/impossible to find if you do not know they exist from
>> the start, and if you ever find one you do not know what they do without
>> reading the source code in detail, eg to know what to give arguments to get
>> an answer.

> At first, we must decide in which cases users will use them. And I don't
> see such cases. I must to know how to grant privileges, how to revoke
> them and how to check existing priveleges. All theese tasks documented
> in GRANT, REVOKE commands and system catalog descriptions.

These are end-user needs.

There are also other needs, such as devs. I see no reason to make the
developer work harder by not providing documentation about available
functions. Tom mention the "acldefault" function that I did not know
existed, and I have read the doc!

So I'm still favorable to documenting all functions:-)

Maybe there could be a special section about special/internal functions,
separate from functions which are more of interest to the end-user? But
for me this is already the purpose of the "System information" sections in
the documentation. Maybe there could be another sub-section about aclitem
related functions in the "System information" section for these.

> Your's patch from another thread closes the last hole - describing default
> privileges in various psql commands.

Yep.

--
Fabien.

In response to

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Adrien NAYRAT 2018-08-03 09:43:31 Re: Explain buffers wrong counter with parallel plans
Previous Message Masahiko Sawada 2018-08-03 08:52:24 Re: [HACKERS] Transactions involving multiple postgres foreign servers, take 2