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.
The Enterprise PostgreSQL Company
In response to
pgsql-docs by date
|Next:||From: Josh Kupershmidt||Date: 2010-10-18 23:56:29|
|Subject: Inaccurate comment for information_schema.triggered_update_columns|
|Previous:||From: Tom Lane||Date: 2010-10-16 14:28:53|
|Subject: Re: Documenting removal of nonnullvalue() and friends |