I finally got around to completing the function-comments cleanup
proposed here:
http://archives.postgresql.org/pgsql-docs/2010-10/msg00041.php
There are now a heck of a lot of boilerplate comments likeDESCR("implementation of + operator");
in pg_proc.h (about 700 of 'em to be exact). My original plan had
involved getting initdb to generate those comments automatically
instead of having to maintain them manually, but I desisted from
that after noticing that there are various cases where we have
multiple operators linking to the same pg_proc entry, so initdb
wouldn't know which one to pick.
But thinking about it this morning, I realize that all those cases
are ones where we've replaced an old spelling of an operator name
with a better choice, and really the old entry is deprecated but
we still have it for compatibility reasons. So we could teach
initdb how to build the desired comments if there were some easy
way for it to recognize the deprecated operators. The obvious
way to do that is to put something like "deprecated, use <@ instead"
in the comment for the deprecated version. This seems like a
good idea from a user's standpoint too, considering that the entire
motivation for this effort was to ensure that \df (and by extension
\do) output will tell you to avoid non-preferred ways of spelling
a function/operator call.
(BTW, the operators in question are @, ~, and @@@ uses that are
now preferred to be spelled <@, @>, and @@ respectively.)
So, two questions:
1. Do people like the idea of marking obsolete operator names this
way? If so, exactly how to mark them? We could try to add
"(deprecated, ...)" at the end of the existing description, or just
replace the description completely. In some of these cases the
existing description is pretty long, making the latter attractive.
2. Given that we do #1, is it really a good idea to generate the
boilerplate comments automatically? The argument I can see against it
is that right now there's a pretty simple coding rule "every pg_proc.h
entry should have a comment". This is less confusing than "every
pg_proc.h entry should have a comment, except those that are linked to
pg_operator entries and aren't meant to be used directly". I'm not
sure that argument outweighs "writing the boilerplate comment is a
PITA", but I'm not sure it doesn't either.
Comments?
regards, tom lane
