Re: pgsql: Fix documentation of argument type of json_agg and jsonb_agg

Tom Lane-2 wrote
> Andrew Dunstan <

> andrew@

> > writes:
>> On 12/22/2014 02:34 PM, Tom Lane wrote:
>>> The actual declaration of the argument type is "anyelement", and I think
>>> we use that to document other such functions.
>
>> Oh, I thought I had seen "expression" there. It looks like we're using
>> "any" elsewhere, so I'll use that. While I'm at it I'll remove the quote
>> marks around the arguments to json_object_agg().
>
> [ looks around... ]  Looks like there are some of each.  Don't know how
> important consistency is here; I'm satisfied with "any", even though it
> doesn't exactly match the catalogs.

Its less a matter of uniformity and more that we don't seem to enforce the
implied semantic difference between "any" and "anyelement".

Based upon:

http://www.postgresql.org/docs/9.4/interactive/datatype-pseudo.html

And the corresponding comment in:

http://www.postgresql.org/docs/9.4/interactive/extend-type-system.html#EXTEND-TYPES-POLYMORPHIC

"any" is not defined to be polymorphic - it is just simply a placeholder for
an unrestricted type.  Thus for functions that are not fully polymorphic
(defined for me as either having multiple inputs or an input and a matched
output) the use of "any" would be appropriate and would imply - if used
consistently - that the type of the output is fixed for all input types.  I
would probably be happy simply saying that the output type has to be
polymorphic and allow for a multiple-input "any" declaration (any, but all
the same).

The main flaw in my reasoning about "any" is that there is no way to define
an "any"-semantic parameter that is restricted to non-array, enums, etc... -
you have to use a polymorphic type no matter the output type if you need
such a restriction.

On the linked table would it be accurate to put a comment that for practical
purposes "any" and "anyelement" are synonyms in their current usage in the
documentation and, if correct, in actual usage?  Also, the word "input" for
"any" seems to be a noise word.  If it is then the "alias" behavior is
implied on the table otherwise there is a distinction that could use
elaboration there.

Making the links to 35.2.5 read:

(Polymorphic - see 35.2.5) would help with immediate context without
diverting the user.

If "any" cannot be used polymorphically that restriction is only defined by
omission and the subtle fact that "any" has not been defined to be a
polymorphic type.

Sorry for the rambling, and I should go and do some experimentation to see
how things work in reality, but that is basically the point since I should
know how/when to use "any" or "anyelement" from the documentation alone; the
choice of wording for the json stuff is simply an artifact of that and the
history of the two types - which may be worth mentioning.

David J.




--
View this message in context:
http://postgresql.nabble.com/pgsql-Fix-documentation-of-argument-type-of-json-agg-and-jsonb-agg-tp5831747p5831782.html
Sent from the PostgreSQL - committers mailing list archive at Nabble.com.