Re: Documenting removal of nonnullvalue() and friends

On Fri, Oct 15, 2010 at 11:40 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Peter Eisentraut <peter_e@gmx.net> writes:
>> On tor, 2010-10-14 at 19:17 -0400, Robert Haas wrote:
>>> Part of the problem, I think, is that people don't necessarily find
>>> this stuff via the documentation.  They fire up psql or pgAdmin and
>>> start typing backslash commands.  They see something good, so they use
>>> it.  How are they to know it's undocumented?
>
>> This could possibly be addressed if we more diligently maintained the
>> system catalogs comments, and then possibly default the comments of
>> undocumented objects to "internal object, don't use".
>
> I thought about this a bit more last night.  It's certainly true that
> a lot of "internal" functions have comments that don't suggest that
> they're not meant to be used directly.  What I think would be a good
> plan for functions that underlie operators is that we move any useful
> comments from pg_proc to pg_operator, and then install a comment in
> pg_proc that says "implementation of operator +" (or whatever the
> operator name is).  This will not only let people know that they should
> use an operator instead, but which one to use, when they find the
> function via \df.
>
> I believe that there are a few cases where we document both the operator
> and the equivalent function, so in those cases both should have the
> regular comment.
>
> The same sort of approach could be used for functions that are meant as
> aggregate support, if they don't have any real stand-alone use.  I think
> most of the other categories of support functions are already pretty
> obviously internal, if there even are any that don't have "internal"
> arguments.
>
> If that sounds like a reasonable plan, I'm willing to have a go at it
> after the commitfest closes.

It's a reasonable plan, but I'm not sure it's going to do a whole lot
of good in practice.  I use \df all the time but \df+ not too often.
I'm halfway tempted to propose that we add a prosupersekret column
that can be set on things we don't intend users to make use of
directly, and then hide them even from \dfS and \df <pattern>.  But I
suspect you'll all just laugh at me.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company