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-14 23:17:49
Message-ID: AANLkTi=B12qZtFDUnk0jukA+0UBoO4578umqSUPxrDzG@mail.gmail.com (view raw or flat)
Thread:
Lists: pgsql-docs
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

In response to

Responses

pgsql-docs by date

Next:From: Simon RiggsDate: 2010-10-15 09:19:56
Subject: Re: formula about the number of WAL files
Previous:From: Tom LaneDate: 2010-10-14 23:15:43
Subject: Re: Documenting removal of nonnullvalue() and friends

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