Re: Documenting removal of nonnullvalue() and friends

Tom Lane 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"
> arguments.
>
> If that sounds like a reasonable plan, I'm willing to have a go at it
> after the commitfest closes.

Tom, any work on this? A TODO?

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +