From: | Robert Haas <robertmhaas(at)gmail(dot)com> |
---|---|
To: | Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> |
Cc: | pgsql-hackers(at)postgresql(dot)org |
Subject: | Re: Mark deprecated operators as such in their comments? |
Date: | 2011-03-03 15:38:47 |
Message-ID: | AANLkTin3VQmc3vb0X5u70JPN-d+Luyp0O+bOdVhamgtn@mail.gmail.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-hackers |
On Thu, Mar 3, 2011 at 10:13 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)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
From | Date | Subject | |
---|---|---|---|
Next Message | Tom Lane | 2011-03-03 15:44:34 | Re: Mark deprecated operators as such in their comments? |
Previous Message | Robert Haas | 2011-03-03 15:36:18 | Re: WAL segments pile up during standalone mode |