Re: JSONPATH documentation

On Mon, Sep 23, 2019 at 1:03 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Alexander Korotkov <a.korotkov@postgrespro.ru> writes:
> > On Sun, Sep 22, 2019 at 9:18 PM Jeff Janes <jeff.janes@gmail.com> wrote:
> > Currently description of jsonpath is divided between datatypes section
> > and functions and operators section.  And yes, this looks cumbersome.
>
> Agreed, but ...
>
> > I think we should move the whole description to the one section.
> > Probably we should move jsonpath description to datatypes section
> > (assuming jsonpath is a datatype) leaving functions and operators
> > section with just SQL-level functions and operators.  What do you
> > think?
>
> ... I don't think that's an improvement.  We don't document detailed
> behavior of a datatype's functions in datatype.sgml, and this seems
> like it would be contrary to that layout.  If anything, I'd merge
> the other way, with only a very minimal description of jsonpath
> (perhaps none?) in datatype.sgml.
>
> While we're whining about this, I find it very off-putting that
> the jsonpath stuff was inserted in the JSON functions section
> ahead of the actual JSON functions.  I think it should have
> gone after them, because it feels like a barely-related interjection
> as it stands.  Maybe there's even a case that it should be
> its own <sect1>, after the "functions-json" section.

Yes, it think moving jsonpath description to own <sect1> is a good
idea.  But I still think we should have complete jsonpath description
in the single place.  What about joining jsonpath description from
both datatypes section and functions and operators section into this
<sect1>, leaving datatypes section with something very brief?

------
Alexander Korotkov
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company