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

Re: Documenting removal of nonnullvalue() and friends

From: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
To: Robert Haas <robertmhaas(at)gmail(dot)com>
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:15:43
Message-ID: 6841.1287098143@sss.pgh.pa.us (view raw or flat)
Thread:
Lists: pgsql-docs
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.

			regards, tom lane

In response to

Responses

pgsql-docs by date

Next:From: Robert HaasDate: 2010-10-14 23:17:49
Subject: Re: Documenting removal of nonnullvalue() and friends
Previous:From: Robert HaasDate: 2010-10-14 23:04:56
Subject: Re: Documenting removal of nonnullvalue() and friends

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