Robert Haas <robertmhaas@gmail.com> writes:
> On Thu, Mar 3, 2011 at 10:13 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> 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.
Well, there is an enforcement mechanism: the regression tests will now
complain if any pg_proc.h entry lacks a comment. What they can't do
very well is enforce that the comment is sanely chosen. In particular
the likely failure mechanism is that someone submits a custom comment
for a function that would be better off being labeled as "implementation
of XXX operator". But AFAICS such a mistake is about equally likely
with either approach, maybe even a tad more so if submitters are forced
to comment every function instead of having an automatic default.
regards, tom lane