Re: new json funcs

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