On Mon, May 20, 2024 at 7:51 PM Amit Langote <amitlangot...@gmail.com> wrote:
>
> Hi Thom,
>>
> > and I think we need to either remove the leading "select" keyword, or
> > uppercase it in the examples.
> >
> > For example (on
> > https://www.postgresql.org/docs/devel/functions-json.html#SQLJSON-QUERY-FUNCTIONS):
> >
> > json_exists ( context_item, path_expression [ PASSING { value AS varname }
> > [, ...]] [ { TRUE | FALSE | UNKNOWN | ERROR } ON ERROR ])
> >
> > Returns true if the SQL/JSON path_expression applied to the context_item
> > using the PASSING values yields any items.
> > The ON ERROR clause specifies the behavior if an error occurs; the default
> > is to return the boolean FALSE value. Note that if the path_expression is
> > strict and ON ERROR behavior is ERROR, an error is generated if it yields
> > no items.
> > Examples:
> > select json_exists(jsonb '{"key1": [1,2,3]}', 'strict $.key1[*] ? (@ > 2)')
> > → t
> > select json_exists(jsonb '{"a": [1,2,3]}', 'lax $.a[5]' ERROR ON ERROR) → f
> > select json_exists(jsonb '{"a": [1,2,3]}', 'strict $.a[5]' ERROR ON ERROR) →
> > ERROR: jsonpath array subscript is out of bounds
> >
> > Examples are more difficult to read when keywords appear to be at the same
> > level as predicates. Plus other examples within tables on the same page
> > don't start with "select", and further down, block examples uppercase
> > keywords. Either way, I don't like it as it is.
>
> I agree that the leading SELECT should be removed from these examples.
> Also, the function names should be capitalized both in the syntax
> description and in the examples, even though other functions appearing
> on this page aren't.
>
> > Separate from this, I think these tables don't scan well (see json_query
> > for an example of what I'm referring to). There is no clear separation of
> > the syntax definition, the description, and the example. This is more a
> > matter for the website mailing list, but I'm expressing it here to check
> > whether others agree.
>
> Hmm, yes, I think I forgot to put <synopsis> around the syntax like
> it's done for a few other functions listed on the page.
>
> How about the attached? Other than the above points, it removes the
> <para> tags from the description text of each function to turn it into
> a single paragraph, because the multi-paragraph style only seems to
> appear in this table and it's looking a bit weird now. Though it's
> also true that the functions in this table have the longest
> descriptions.
>
Note that scalar strings returned by <function>json_value</function>
always have their quotes removed, equivalent to specifying
- <literal>OMIT QUOTES</literal> in <function>json_query</function>.
+ <literal>OMIT QUOTES</literal> in <function>JSON_QUERY</function>.
"Note that scalar strings returned by <function>json_value</function>"
should be
"Note that scalar strings returned by <function>JSON_VALUE</function>"
generally <synopsis> section no need indentation?
you removed <para> tag for description of JSON_QUERY, JSON_VALUE, JSON_EXISTS.
JSON_EXISTS is fine, but for
JSON_QUERY, JSON_VALUE, the description section is very long.
splitting it to 2 paragraphs should be better than just a single paragraph.
since we are in the top level table section: <table
id="functions-sqljson-querying">
so there will be no ambiguity of what we are referring to.
one para explaining what this function does, and its return value,
one para having a detailed explanation should be just fine?
