Re: Documenting removal of nonnullvalue() and friends

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