Skip site navigation (1) Skip section navigation (2)

Re: Documenting removal of nonnullvalue() and friends

From: Robert Haas <robertmhaas(at)gmail(dot)com>
To: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Cc: Peter Eisentraut <peter_e(at)gmx(dot)net>, Josh Kupershmidt <schmiddy(at)gmail(dot)com>, pgsql-docs(at)postgresql(dot)org
Subject: Re: Documenting removal of nonnullvalue() and friends
Date: 2010-10-18 20:34:13
Message-ID: (view raw, whole thread or download thread mbox)
Lists: pgsql-docs
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
The Enterprise PostgreSQL Company

In response to

pgsql-docs by date

Next:From: Josh KupershmidtDate: 2010-10-18 23:56:29
Subject: Inaccurate comment for information_schema.triggered_update_columns
Previous:From: Tom LaneDate: 2010-10-16 14:28:53
Subject: Re: Documenting removal of nonnullvalue() and friends

Privacy Policy | About PostgreSQL
Copyright © 1996-2017 The PostgreSQL Global Development Group