Re: Documenting removal of nonnullvalue() and friends

On Thu, Oct 14, 2010 at 7:15 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Robert Haas <robertmhaas(at)gmail(dot)com> writes:
>> On Thu, Oct 14, 2010 at 6:07 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)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.

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?

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