On Fri, Oct 15, 2010 at 11:40 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
>> On tor, 2010-10-14 at 19:17 -0400, Robert Haas wrote:
>>> Part of the problem, I think, is that people don't necessarily find
>>> this stuff via the documentation. They fire up psql or pgAdmin and
>>> start typing backslash commands. They see something good, so they use
>>> it. How are they to know it's undocumented?
>> This could possibly be addressed if we more diligently maintained the
>> system catalogs comments, and then possibly default the comments of
>> undocumented objects to "internal object, don't use".
> 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). This will not only let people know that they should
> use an operator instead, but which one to use, when they find the
> function via \df.
> I believe that there are a few cases where we document both the operator
> and the equivalent function, so in those cases both should have the
> regular comment.
> The same sort of approach could be used for functions that are meant as
> aggregate support, if they don't have any real stand-alone use. I think
> most of the other categories of support functions are already pretty
> obviously internal, if there even are any that don't have "internal"
> If that sounds like a reasonable plan, I'm willing to have a go at it
> after the commitfest closes.
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'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.
The Enterprise PostgreSQL Company
In response to
pgsql-docs by date
|Next:||From: Alvaro Herrera||Date: 2010-10-16 04:30:14|
|Subject: Re: description of translate()|
|Previous:||From: Tom Lane||Date: 2010-10-15 15:40:53|
|Subject: Re: Documenting removal of nonnullvalue() and friends |