Re: remaining sql/json patches

On Tue, Mar 5, 2024 at 9:22 AM Amit Langote <amitlangote09(at)gmail(dot)com> wrote:
>
> Thanks for the heads up. Attaching rebased patches.
>

Walking through the v41-0001-Add-SQL-JSON-query-functions.patch documentation.
I found some minor cosmetic issues.

+ <para>
+ <literal>select json_query(jsonb '{"a": "[1, 2]"}', 'lax $.a'
RETURNING int[] OMIT QUOTES);</literal>
+ <returnvalue></returnvalue>
+ </para>
this example is not so good, it returns NULL, makes it harder to
render the result.

+ <replaceable>context_item</replaceable> (the document); seen
+ <xref linkend="functions-sqljson-path"/> for more details on what
+ <replaceable>path_expression</replaceable> can contain.
"seen" should be "see"?

+ <para>
+ This function must return a JSON string, so if the path expression
+ returns multiple SQL/JSON items, you must wrap the result using the
+ <literal>WITH WRAPPER</literal> clause. If the wrapper is
"must" may be not correct?
since we have a RETURNING clause.
"generally" may be more accurate, I think.
maybe we can rephrase the sentence:
+ This function generally return a JSON string, so if the path expression
+ yield multiple SQL/JSON items, you must wrap the result using the
+ <literal>WITH WRAPPER</literal> clause

+ is spcified, the returned value will be of type <type>text</type>.
+ If no <literal>RETURNING</literal> is spcified, the returned value will
two typos, and should be "specified".

+ Note that if the <replaceable>path_expression</replaceable>
+ is <literal>strict</literal> and <literal>ON ERROR</literal> behavior
+ is <literal>ON ERROR</literal>, an error is generated if it yields no
+ items.

may be the following:
+ Note that if the <replaceable>path_expression</replaceable>
+ is <literal>strict</literal> and <literal>ON ERROR</literal> behavior
+ is <literal>ERROR</literal>, an error is generated if it yields no
+ items.

most of the place, you use
<replaceable>path_expression</replaceable>
but there are two place you use:
<type>path_expression</type>
I guess that's ok, but the appearance is different.
<replaceable> more prominent. Anyway, it is a minor issue.

+ <function>json_query</function>. Note that scalar strings returned
+ by <function>json_value</function> always have their quotes removed,
+ equivalent to what one would get with <literal>OMIT QUOTES</literal>
+ when using <function>json_query</function>.

I think we can simplify it like the following:

+ <function>json_query</function>. Note that scalar strings returned
+ by <function>json_value</function> always have their quotes removed,
+ equivalent to <literal>OMIT QUOTES</literal>
+ when using <function>json_query</function>.