Re: JSONPATH documentation

On Mon, Sep 23, 2019 at 1:03 AM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Alexander Korotkov <a(dot)korotkov(at)postgrespro(dot)ru> writes:
> > On Sun, Sep 22, 2019 at 9:18 PM Jeff Janes <jeff(dot)janes(at)gmail(dot)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