Re: Mark deprecated operators as such in their comments? - Mailing list pgsql-hackers

On Thu, Mar 3, 2011 at 10:13 AM, Tom Lane <tgl@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