On Tue, Nov 22, 2022 at 2:10 PM Bruce Momjian <br...@momjian.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"
