To: Josh Kupershmidt <schmiddy@gmail.com>
cc: Peter Eisentraut <peter_e@gmx.net>, Robert Haas <robertmhaas@gmail.com>,
	pgsql-docs@postgresql.org
Subject: Re: Documenting removal of nonnullvalue() and friends 
In-reply-to: <AANLkTim=ExkXOAqGBAd6Uqnnq9X9L6UC9q2_bZGR792a@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>
	<AANLkTim=ExkXOAqGBAd6Uqnnq9X9L6UC9q2_bZGR792a@mail.gmail.com>
Comments: In-reply-to Josh Kupershmidt <schmiddy@gmail.com>
	message dated "Thu, 14 Oct 2010 10:29:42 -0400"
Date: Thu, 14 Oct 2010 10:38:11 -0400
Message-ID: <18056.1287067091@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>

Josh Kupershmidt <schmiddy@gmail.com> writes:
> I'm curious now, though: are there any other functions which we're
> leaving intentionally undocumented?

Practically all the functions underlying operators are undocumented, eg
int4pl(int, int).  (If you consider IS NOT NULL to be an operator, then
nonnullvalue is exactly one of those.)  It's possible for people to use
those directly but it's discouraged.  I do *not* want to add them to the
docs, because (a) I do *not* want people to use them directly and (b)
there are a hell of a lot of them, so the docs would get much much
longer with no actual added value.

Perhaps what we should really add to the docs is a statement that use of
undocumented functions is deprecated and we will not be responsible when
your code breaks because one of those is changed or removed.

			regards, tom lane