Re: new json funcs

On 01/10/2014 01:58 PM, Tom Lane wrote:
> Andrew Dunstan <andrew(at)dunslane(dot)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'. In some cases involving
legacy
-- names for operators, there are multiple operators referencing the
same
-- pg_proc entry, so ignore operators whose comments say they are
deprecated.
-- We also have a few functions that are both operator 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