Re: Documenting removal of nonnullvalue() and friends

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.

> 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.

regards, tom lane