On Tue, 2022-11-29 at 16:26 -0500, Kirk Wolak wrote: > On Mon, Nov 28, 2022 at 12:45 AM Tom Lane <tgl@sss.pgh.pa.us> wrote: > > Laurenz Albe <laurenz.albe@cybertec.at> writes: > > > Now I think that is taking it too far. Your code sample would be great > > > for a tutorial, but it is too elaborate for the technical documentation. > > > The example should focus on the sequence functions, but more than half > > > of the code describes other parts of PostgreSQL: > > > > Yeah, that stuff seems quite out of place here. > > > > > I am alright with having a CREATE TABLE with a DEFAULT and an INSERT or two; > > > whatever it takes to show the functions in a realistic scenario. > > > For example, you could INSERT a row that overrides the DEFAULT, then call > > > "setval()" to readjust the sequence. > > > > I don't believe we have such detail around very many, if indeed any, > > of our other functions' documentation. > > > > regards, tom lane > > > All changes specified have been addressed. > The Example is significantly reduced, but readable. > The extra "SELECT "'s have been removed off of the inline examples, excluding the existing paragraph. > > This is the smallest possible change, that still has an example. > > The "Example" is not <title> as every attempt to make it such fails the LINT process.
You can have <title> only after the start of a section.
The new examples in the table don't really add anything to the function declaration...
I realized that there already are some examples in the CREATE SEQUENCE documentation, so what about linking there instead of writing more examples?
The attached patch does that and removes the less useful examples. What do you think?
Yours, Laurenz Albe
+1
While I agree with the conclusion that the function signature is an example, and having more than one for these is probably overkill, we can address the OP's complaint quite easily by doing what we do in many other places, give each parameter in the function signature a name. I've modified v9 to include those and attach it here as v10. I do think this suffices as a response to this complaint.
Bikeshedding on the names for setval, and maybe an attempt to incorporate the parameter name into the prose, can be considered, though.
My thoughts regarding incorporating pg_get_serial_sequence and usage of these functions in a more common, GENERATED AS IDENTITY environment, can be considered in a separate thread should I or anyone else wish to do so.