On Tue, Nov 22, 2022 at 8:42 PM Kirk Wolak <wol...@gmail.com> wrote: > > > 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. >
We've only fairly recently made incorporating useful and expansive examples into the reference part of the documentation generally doable. I agree that this particular one warrants such an example. If you are willing to do the harder work you describe below, submit a patch for this. It's specific, small, an improvement, and nothing Bruce said indicates it isn't wanted, he just focused on a different aspect of the complaint. > 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! > > Sure, and the decades old documentation written for the book era, not YouTube and interactive tutorials, doesn't cater for that audience. That isn't going to change at this point, and that is a good thing. But that doesn't mean specific improvements cannot be made. > > 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" > The wiki is an excellent place to prototype and coordinate. Beyond that, this idea falls outside what should be discussed on this thread. Here, let's either patch the docs with some examples, or not. David J.
