Re: Documenting removal of nonnullvalue() and friends

On Sat, Oct 16, 2010 at 10:28 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Robert Haas <robertmhaas(at)gmail(dot)com> writes:
>> On Fri, Oct 15, 2010 at 11:40 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>>> I thought about this a bit more last night.  It's certainly true that
>>> a lot of "internal" functions have comments that don't suggest that
>>> they're not meant to be used directly.  What I think would be a good
>>> plan for functions that underlie operators is that we move any useful
>>> comments from pg_proc to pg_operator, and then install a comment in
>>> pg_proc that says "implementation of operator +" (or whatever the
>>> operator name is).
>
>> It's a reasonable plan, but I'm not sure it's going to do a whole lot
>> of good in practice.  I use \df all the time but \df+ not too often.
>
> I don't think that argument holds a lot of water.  If you found an
> interesting-looking function via \df, wouldn't you make at least some
> effort to verify what it does before putting it into a production query?
> I should think you'd at least look into \df+ or the SGML docs.

Maybe. But even if I did, I am not known for being the least cautious
person among my set of acquaintances.

>> I'm halfway tempted to propose that we add a prosupersekret column
>> that can be set on things we don't intend users to make use of
>> directly, and then hide them even from \dfS and \df <pattern>.  But I
>> suspect you'll all just laugh at me.
>
> I've occasionally toyed with the idea of moving all non-public functions
> into a separate schema, say "pg_internal", which wouldn't be in the
> standard search path (and thus ordinary \df wouldn't see it).  That
> would be nice from a cleanliness standpoint, but there are downsides
> too.  The big problem is that it moves this endeavor out of the realm of
> "let's improve the documentation" and into the realm of "let's
> intentionally break every app that dared to use a non-public function".
> It seems clear to me that that's a huge overreaction.  99% of the time
> it's no big deal if somebody uses one of these directly; as portability
> problems go, this was a tiny and easily solved issue.

It probably would have been a good idea to design it that way
originally, but I think it's too late to do that now. That would
break a lot more stuff than what I proposed, because you'd really be
moving it, not just sweeping it under the rug.

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