From: Tom Lane <tgl@sss.pgh.pa.us>
To: Robert Haas <robertmhaas@gmail.com>
Cc: Peter Eisentraut <peter_e@gmx.net>
Cc: Josh Kupershmidt <schmiddy@gmail.com>
Cc: pgsql-docs@postgresql.org
Subject: Re: Documenting removal of nonnullvalue() and friends
Date: Thu, 14 Oct 2010 19:15:43 -0400
Message-ID: <6841.1287098143@sss.pgh.pa.us> (raw)
In-Reply-To: <AANLkTikUKtngdLHCeqi=iERU6ydvQRcsW8EoaSwkrT3o@mail.gmail.com>
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>
Robert Haas <robertmhaas@gmail.com> writes:
> On Thu, Oct 14, 2010 at 6:07 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> They should assume the lack of documentation is intentional. Six or
>> seven years ago your argument might have held some water, but we've
>> been quite rigorous about requiring externally-visible features to be
>> documented from the get-go.
> That just doesn't match my experience. We goof. People find it.
Sure, there are bugs of that sort, just like we have bugs of many other
sorts. When people find them, we fix them. But the general principle
is that functions and operators that are meant to be used directly from
SQL are shown in the SGML documentation; and those that aren't, aren't.
There are probably upwards of a thousand entries in pg_proc that are
not, and never were, meant to be directly invoked from SQL. (In
particular, with 706 entries in pg_operator, there are presumably about
700 functions underlying operators; and then you've got functions
underlying aggregates, index AM support functions, selectivity
estimation functions, text search support functions, foreign data
wrapper functions, yadda yadda.) It is not sane to propose documenting
those individually, not only from the standpoint of docs bloat but
because documenting them would encourage people to call them, which is
exactly not the result we want.
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, robertmhaas@gmail.com, peter_e@gmx.net, schmiddy@gmail.com
Subject: Re: Documenting removal of nonnullvalue() and friends
In-Reply-To: <6841.1287098143@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