Thread: Incorrect Syntax in Function Syntax diagram
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
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