Re: Doc Rework: Section 9.16.13 SQL/JSON Query Functions - Mailing list pgsql-hackers

On Fri, Jul 5, 2024 at 8:35 PM Amit Langote <amitlangote09@gmail.com> wrote:
> Please check the attached.  I've also added <itemizedlist> lists as I
> remember you had proposed before to make the functions' descriptions a
> bit more readable -- I'm persuaded. :-)
>


json_exists
"Returns true if the SQL/JSON path_expression applied to the
context_item using the PASSING values yields any items."
now you changed to
<<
Returns true if the SQL/JSON path_expression applied to the
context_item. path_expression can reference variables named in the
PASSING clause.
<<
 Is it wrong?


        For both <literal>ON EMPTY</literal>and <literal>ON ERROR</literal>,
        specifying <literal>ERROR</literal> will cause an error to be
thrown with
        the appropriate message. Other options include returning a SQL NULL, an
need one more whitespace. should be:
        For both <literal>ON EMPTY</literal> and <literal>ON ERROR</literal>,


        Note that an error will be thrown if multiple values are returned and
        <literal>WITHOUT WRAPPER</literal> is specified.
since not specify error on error, then no error will be thrown. maybe
rephrase to
        It will be evaulated as error if multiple values are returned and
        <literal>WITHOUT WRAPPER</literal> is specified.


       <para>
        For both <literal>ON EMPTY</literal> and <literal>ON ERROR</literal>,
        specifying <literal>ERROR</literal> will cause an error to be
thrown with
        the appropriate message. Other options include returning a SQL NULL, an
        empty array or object (array by default), or a user-specified expression
        that can be coerced to jsonb or the type specified in
<literal>RETURNING</literal>.
        The default when <literal>ON EMPTY</literal> or <literal>ON
ERROR</literal>
        is not specified is to return a SQL NULL value when the respective
        situation occurs.
       </para>
in here, "empty array or object (array by default)",
I don't think people can understand the meaning of "(array by default)" .

"or a user-specified expression"
maybe we can change to
"or a user-specified
        <literal>DEFAULT</literal> <replaceable>expression</replaceable>"
I think "user-specified expression" didn't have much link with
"<literal>DEFAULT</literal> <replaceable>expression</replaceable>"


<replaceable>path_expression</replaceable> can reference variables named
        in the <literal>PASSING</literal> clause.
do we need "The <replaceable>path_expression</replaceable>"?
also maybe we can add
+ In <literal>PASSING</literal> clause, <replaceable>varname</replaceable> is
+        the variables name, <replaceable>value</replaceable> is the
+ variables' value.
we can add a PASSING clause example from sqljson_queryfuncs.sql ,
since all three functions can use it.



JSON_VALUE:
<<an error is thrown if that's not the case (though see the discussion
of ON ERROR below).
then
<< The ON ERROR and ON EMPTY clauses have similar semantics as
mentioned in the description of JSON_QUERY, except the set of values
returned in lieu of throwing an error is different.

you first refer "below", then director to JSON_QUERY on error, on
empty description.
is the correct usage of "below"?
"(though see the discussion of ON ERROR below)."
i am not sure the meaning of "though" even watched this
https://www.youtube.com/watch?v=r-LphuCKQ0Q