Incorrect Syntax in Function Syntax diagram

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.

"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

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.

"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