On Thu, Mar 3, 2011 at 10:13 AM, Tom Lane <t...@sss.pgh.pa.us> wrote: > 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 like > DESCR("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.
"Deprecated, use <blah> instead"? > 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. I think the chances that future patches will follow the more complex coding rule are near zero, absent some type of automated enforcement mechanism. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
