Skip site navigation (1) Skip section navigation (2)

Re: Documenting removal of nonnullvalue() and friends

From: Robert Haas <robertmhaas(at)gmail(dot)com>
To: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Cc: Peter Eisentraut <peter_e(at)gmx(dot)net>, Josh Kupershmidt <schmiddy(at)gmail(dot)com>, pgsql-docs(at)postgresql(dot)org
Subject: Re: Documenting removal of nonnullvalue() and friends
Date: 2010-10-16 01:44:46
Message-ID: AANLkTi=rs6gTkn47msLeP6bbX+erpOfThFAkEg8GFjZR@mail.gmail.com (view raw or flat)
Thread:
Lists: pgsql-docs
On Fri, Oct 15, 2010 at 11:40 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Peter Eisentraut <peter_e(at)gmx(dot)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

In response to

Responses

pgsql-docs by date

Next:From: Alvaro HerreraDate: 2010-10-16 04:30:14
Subject: Re: description of translate()
Previous:From: Tom LaneDate: 2010-10-15 15:40:53
Subject: Re: Documenting removal of nonnullvalue() and friends

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group