Re: nextval parameter is not clear

On Sat, Dec 3, 2022 at 8:03 PM Kirk Wolak <wolakk(at)gmail(dot)com> wrote:

> On Thu, Dec 1, 2022 at 4:21 PM Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)at>
> wrote:
>
>> On Tue, 2022-11-29 at 16:26 -0500, Kirk Wolak wrote:
>> > On Mon, Nov 28, 2022 at 12:45 AM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>> > > Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)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.

David J.