On Tue, Oct 18, 2022 at 08:17:12AM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/14/functions-sequence.html
> Description:
>
> https://www.postgresql.org/docs/14/functions-sequence.html
>
> I don't see here any hints about how to use this function, and what the
> Maybe add some links to other topics or clarify examples for nextval here.
Uh, the last sentence in that section says:
The sequence to be operated on by a sequence function is specified by a
regclass argument, which is simply the OID of the sequence in the
pg_class system catalog. You do not have to look up the OID by hand,
however, since the regclass data type's input converter will do the work
for you. See Section 8.19 for details.
As someone who is "newer", I'd like to point out that a "clarifying example" as
simple as SELECT nextval("your_seq"::regclass);
is about 100 times more CLEAR about the essence than that paragraph.
And, yes, I read the page, and I've seen the examples just one paragraph lower.
A huge majority of us are hyper-visual, and learn by example. But that example
below does not translate to this example... Unless you already know it!
I've been frustrated many times to find the documentation, and then struggle
trying to envision how the ultimate code/syntax truly reads.
I've thought about this, and I believe having a GIGANTIC page of PG SQL code,
that could be referenced and linked, would be a WONDERFUL thing.
Then a page like this could literally have a link: "see example".
Everyone who NORMALLY reads these emails are not typically struggling
with the syntax. But the people going to documentation often are!
Regards
PS: I am willing to help create that gigantic page, if we can standardize a way to link to it.
PPS: Even to the point of successive refinement. Over time, we may add "do this / not this"
