From: Tom Lane <tgl@sss.pgh.pa.us>
To: Peter Eisentraut <peter_e@gmx.net>
Cc: Robert Haas <robertmhaas@gmail.com>
Cc: Josh Kupershmidt <schmiddy@gmail.com>
Cc: pgsql-docs@postgresql.org
Subject: Re: Documenting removal of nonnullvalue() and friends
Date: Fri, 15 Oct 2010 11:40:53 -0400
Message-ID: <21407.1287157253@sss.pgh.pa.us> (raw)
In-Reply-To: <1287156419.9739.1.camel@vanquo.pezone.net>
References: <AANLkTikr84KaL_EQECtvfnKkq0f=abHi4s+9Cq7LSOSo@mail.gmail.com>
<AANLkTikT01KcHaEfJRBepM6ZGncD59Sn1g9MEE-XPpWX@mail.gmail.com>
<AANLkTi=Av3AJ9DAyyO758OKabzEks-pNQWm=ntTMLHkH@mail.gmail.com>
<AANLkTikH6JF0FrwJBDaYpUN_TW=3t=Syj3pnzJ7CX1-A@mail.gmail.com>
<1287064806.9532.5.camel@vanquo.pezone.net>
<AANLkTikXfVVpnaDptPZpmShokB3caP9xA0ewOzMqE0Q_@mail.gmail.com>
<5718.1287094063@sss.pgh.pa.us>
<AANLkTikUKtngdLHCeqi=iERU6ydvQRcsW8EoaSwkrT3o@mail.gmail.com>
<6841.1287098143@sss.pgh.pa.us>
<AANLkTi=B12qZtFDUnk0jukA+0UBoO4578umqSUPxrDzG@mail.gmail.com>
<1287156419.9739.1.camel@vanquo.pezone.net>
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.
regards, tom lane
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, peter_e@gmx.net, robertmhaas@gmail.com, schmiddy@gmail.com
Subject: Re: Documenting removal of nonnullvalue() and friends
In-Reply-To: <21407.1287157253@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox