Re: nextval parameter is not clear

On Tue, Nov 22, 2022 at 2:10 PM Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> 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"