Horton

Thread

Commits

  1. Doc: fix confusion about LEAKPROOF in syntax summaries.

  1. Incorrect Syntax in Function Syntax diagram

    The Post Office <noreply@postgresql.org> — 2021-06-23T10:18:15Z

    The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/13/sql-createfunction.html
Description:

| IMMUTABLE | STABLE | VOLATILE | [ NOT ] LEAKPROOF

[ NOT ] LEAKPROOF  is accepting separately ,
So why you written [ NOT ] LEAKPROOF with | IMMUTABLE | STABLE | VOLATILE | 


Please separate the [ NOT ] LEAKPROOF from the OR list


Note: Your documentation must be correct

  2. Re: Incorrect Syntax in Function Syntax diagram

    David G. Johnston <david.g.johnston@gmail.com> — 2021-06-23T15:16:49Z

    On Wed, Jun 23, 2021 at 6:31 AM PG Doc comments form <noreply@postgresql.org>
wrote:

> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/13/sql-createfunction.html
> Description:
>
> | IMMUTABLE | STABLE | VOLATILE | [ NOT ] LEAKPROOF
>
> [ NOT ] LEAKPROOF  is accepting separately ,
> So why you written [ NOT ] LEAKPROOF with | IMMUTABLE | STABLE | VOLATILE
> |
>
>
The commit message doesn't say - but I can see how from a technical
perspective that the claim that something is immutable is considered
similar to a claim that something has no side effects, thus there is a
connection.  As noted below, the fact that the first three are mutually
exclusive while leakproof is not is convincing enough a reason to list
leakproof separately.

Please separate the [ NOT ] LEAKPROOF from the OR list
>

I would agree, and would add that I wonder whether the syntax for the three
mutually exclusive options should be shown as such instead of having to
read that in the description notes.  Does writing < | { IMMUTABLE | STABLE
| VOLATILE } > work?

Note: Your documentation must be correct
>

Is that so? It is a good thing then that it is presently correct and that
this is just a readability suggestion.  The presence of them all on the
same line does not by itself imply any kind of relationship in the actual
grammar.

David J.

  3. Re: Incorrect Syntax in Function Syntax diagram

    Tom Lane <tgl@sss.pgh.pa.us> — 2021-06-23T15:29:11Z

    "David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Wed, Jun 23, 2021 at 6:31 AM PG Doc comments form <noreply@postgresql.org>
> wrote:
> Please separate the [ NOT ] LEAKPROOF from the OR list

> I would agree, and would add that I wonder whether the syntax for the three
> mutually exclusive options should be shown as such instead of having to
> read that in the description notes.  Does writing < | { IMMUTABLE | STABLE
> | VOLATILE } > work?

Yeah.  The way it's written fails to show, except via formatting,
that IMMUTABLE/STABLE/VOLATILE are mutually exclusive; and then
somebody came along and destroyed the formatting.  I agree both
with adding braces and with putting LEAKPROOF on its own line.
The latter is/should be only cosmetic; but the rest of the list
has one line per independent option, and LEAKPROOF is surely
independent of the volatility options.

			regards, tom lane

  4. Re: Incorrect Syntax in Function Syntax diagram

    David G. Johnston <david.g.johnston@gmail.com> — 2021-06-23T15:41:56Z

    On Wed, Jun 23, 2021 at 8:29 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:

> Yeah.  The way it's written fails to show, except via formatting,
> that IMMUTABLE/STABLE/VOLATILE are mutually exclusive;
>

It seems the STRICT -ness line needs brackets too then.

Also, back to volatility, volatile is the default option though due to
alphabetical order it is shown last with no indication it is the default.
Do we have an existing convention in the syntax section to indicate
defaults, either with emphasis, placement, or even an annotation like "*"?

David J.

  5. Re: Incorrect Syntax in Function Syntax diagram

    Tom Lane <tgl@sss.pgh.pa.us> — 2021-06-23T16:07:29Z

    "David G. Johnston" <david.g.johnston@gmail.com> writes:
> Do we have an existing convention in the syntax section to indicate
> defaults, either with emphasis, placement, or even an annotation like "*"?

No.  The syntax diagrams verge on unreadability already, so I'm
unconvinced that trying to overload them with this issue would be
wise.

			regards, tom lane