On 01/10/2014 01:58 PM, Tom Lane wrote:
> Andrew Dunstan <andrew@dunslane.net> writes:
>> On 01/10/2014 01:27 PM, Tom Lane wrote:
>>> See commits 94133a935414407920a47d06a6e22734c974c3b8 and
>>> 908ab80286401bb20a519fa7dc7a837631f20369.
>> OK, I can fix that I guess.
> Sure, just remove the DESCR comments for the functions that aren't meant
> to be used directly.
>
> I don't think this is back-patchable, but it's a minor point, so at least
> for me a fix in HEAD is sufficient.
>
> I wonder whether we should add an opr_sanity test verifying that operator
> implementation functions don't have their own comments? The trouble is
> that there are a few that are supposed to, but maybe that list is stable
> enough that it'd be okay to memorialize in the expected output.
>
>
Well, that would be ok as long as there was a comment in the file so
that developers don't just think it's OK to extend the list (it's a bit
like part of the reason we don't allow shift/reduce conflicts - if we
allowed them people would just keep adding more, and they wouldn't stick
out like a sore thumb.)
The comment in the current test says:
-- Check that operators' underlying functions have suitable comments, -- namely 'implementation of XXX operator'.
Insome cases involving legacy -- names for operators, there are multiple operators referencing the same --
pg_procentry, so ignore operators whose comments say they are deprecated. -- We also have a few functions that are
bothoperator support and meant to -- be called directly; those should have comments matching their operator.
The history here is that originally I was intending to have these
functions documented, and so the descriptions were made to match the
operator descriptions, so that we didn't get a failure on this test.
Later we decided not to document them as part of last release's
bike-shedding, but the function descriptions didn't get changed / removed.
cheers
andrew