Tom Lane wrote: > Peter Eisentraut <[email protected]> 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 <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
