Horton

Thread

Commits

  1. Doc: fix parameter names in the docs of a couple of functions.

  1. Wrong parameter names for make_interval (Postgres 13)

    shammat@gmx.net — 2020-10-05T13:56:46Z

    There is a typo in the parameter names of the make_interval() function.

The parameter names are all defined with plural, not singular as it is shown
in the Postgres 13 manual.

So instead of

    make_interval ( [ year int [, month int [, week int [, day int [, hour int [, min int [, sec double precision ]]]]]]] )

it should be

    make_interval ( [ years int [, months int [, weeks int [, days int [,hours int [, mins int [, secs double precision ]]]]]]] )

Thomas

  2. Re: Wrong parameter names for make_interval (Postgres 13)

    Pavel Stehule <pavel.stehule@gmail.com> — 2020-10-05T14:33:46Z

    po 5. 10. 2020 v 15:56 odesílatel Thomas Kellerer <shammat@gmx.net> napsal:

> There is a typo in the parameter names of the make_interval() function.
>
> The parameter names are all defined with plural, not singular as it is
> shown
> in the Postgres 13 manual.
>
> So instead of
>
>     make_interval ( [ year int [, month int [, week int [, day int [, hour
> int [, min int [, sec double precision ]]]]]]] )
>
> it should be
>
>     make_interval ( [ years int [, months int [, weeks int [, days int
> [,hours int [, mins int [, secs double precision ]]]]]]] )
>

this syntax is not correct too

It should be

    make_interval( years int default 0, month int default 0, days int
default 0, hours int default 0, secs double precision default 0)

Regards

Pavel



> Thomas
>
>
>

  3. Re: Wrong parameter names for make_interval (Postgres 13)

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-10-05T15:53:58Z

    Pavel Stehule <pavel.stehule@gmail.com> writes:
> po 5. 10. 2020 v 15:56 odesílatel Thomas Kellerer <shammat@gmx.net> napsal:
>> So instead of
>> make_interval ( [ year int [, month int [, week int [, day int [, hour
>> int [, min int [, sec double precision ]]]]]]] )
>> it should be
>> make_interval ( [ years int [, months int [, weeks int [, days int
>> [,hours int [, mins int [, secs double precision ]]]]]]] )

Right, fixed.

> this syntax is not correct too
> It should be
>     make_interval( years int default 0, month int default 0, days int
> default 0, hours int default 0, secs double precision default 0)

IIRC, I intentionally changed that in v13; the existence of the defaults
is sufficiently covered by the text "... fields, each of which can default
to zero".  I think that was partly motivated by trying to get the function
signature to fit into limited space.  The final docs-table design we ended
up with might allow undoing it, but I don't see any real reason to.  The
other way is more verbose and not any clearer.

I spent a little bit of time scanning for other discrepancies between
func.sgml and pg_proc.proargnames, and found several, mostly though
not exclusively in the JSON functions.  In these other cases, though,
I think there might be a good argument for making pg_proc fit the docs
not the other way around.  In the JSON functions, for example, pg_proc
randomly has some functions calling the main JSON[B] input "target"
while others call it "from_json" or "json_in".  I'm not real sure
which of those names is preferable, but inconsistency is not preferable.

			regards, tom lane

  4. Re: Wrong parameter names for make_interval (Postgres 13)

    Pavel Stehule <pavel.stehule@gmail.com> — 2020-10-05T16:48:14Z

    po 5. 10. 2020 v 17:53 odesílatel Tom Lane <tgl@sss.pgh.pa.us> napsal:

> Pavel Stehule <pavel.stehule@gmail.com> writes:
> > po 5. 10. 2020 v 15:56 odesílatel Thomas Kellerer <shammat@gmx.net>
> napsal:
> >> So instead of
> >> make_interval ( [ year int [, month int [, week int [, day int [, hour
> >> int [, min int [, sec double precision ]]]]]]] )
> >> it should be
> >> make_interval ( [ years int [, months int [, weeks int [, days int
> >> [,hours int [, mins int [, secs double precision ]]]]]]] )
>
> Right, fixed.
>
> > this syntax is not correct too
> > It should be
> >     make_interval( years int default 0, month int default 0, days int
> > default 0, hours int default 0, secs double precision default 0)
>
> IIRC, I intentionally changed that in v13; the existence of the defaults
> is sufficiently covered by the text "... fields, each of which can default
> to zero".  I think that was partly motivated by trying to get the function
> signature to fit into limited space.  The final docs-table design we ended
> up with might allow undoing it, but I don't see any real reason to.  The
> other way is more verbose and not any clearer.
>

I don't understand,

the syntax [ a [, b]] means

so a and b are optional, but b can be used only when a is used. But for
make_interval I can use "months" arguments without specification of "years"
argument.

I don't know the correct BNF for arguments with default values, but using
this doesn't look correct.

Regards

Pavel



> I spent a little bit of time scanning for other discrepancies between
> func.sgml and pg_proc.proargnames, and found several, mostly though
> not exclusively in the JSON functions.  In these other cases, though,
> I think there might be a good argument for making pg_proc fit the docs
> not the other way around.  In the JSON functions, for example, pg_proc
> randomly has some functions calling the main JSON[B] input "target"
> while others call it "from_json" or "json_in".  I'm not real sure
> which of those names is preferable, but inconsistency is not preferable.
>
>                         regards, tom lane
>

  5. Re: Wrong parameter names for make_interval (Postgres 13)

    Pavel Stehule <pavel.stehule@gmail.com> — 2020-10-05T16:56:33Z

    po 5. 10. 2020 v 18:48 odesílatel Pavel Stehule <pavel.stehule@gmail.com>
napsal:

>
>
> po 5. 10. 2020 v 17:53 odesílatel Tom Lane <tgl@sss.pgh.pa.us> napsal:
>
>> Pavel Stehule <pavel.stehule@gmail.com> writes:
>> > po 5. 10. 2020 v 15:56 odesílatel Thomas Kellerer <shammat@gmx.net>
>> napsal:
>> >> So instead of
>> >> make_interval ( [ year int [, month int [, week int [, day int [, hour
>> >> int [, min int [, sec double precision ]]]]]]] )
>> >> it should be
>> >> make_interval ( [ years int [, months int [, weeks int [, days int
>> >> [,hours int [, mins int [, secs double precision ]]]]]]] )
>>
>> Right, fixed.
>>
>> > this syntax is not correct too
>> > It should be
>> >     make_interval( years int default 0, month int default 0, days int
>> > default 0, hours int default 0, secs double precision default 0)
>>
>> IIRC, I intentionally changed that in v13; the existence of the defaults
>> is sufficiently covered by the text "... fields, each of which can default
>> to zero".  I think that was partly motivated by trying to get the function
>> signature to fit into limited space.  The final docs-table design we ended
>> up with might allow undoing it, but I don't see any real reason to.  The
>> other way is more verbose and not any clearer.
>>
>
> I don't understand,
>
> the syntax [ a [, b]] means
>
> so a and b are optional, but b can be used only when a is used. But for
> make_interval I can use "months" arguments without specification of "years"
> argument.
>
> I don't know the correct BNF for arguments with default values, but using
> this doesn't look correct.
>

I forgot the behavior of positional  arguments. So this syntax is correct.
I am sorry for the noise.

Regards

Pavel


> Regards
>
> Pavel
>
>
>
>> I spent a little bit of time scanning for other discrepancies between
>> func.sgml and pg_proc.proargnames, and found several, mostly though
>> not exclusively in the JSON functions.  In these other cases, though,
>> I think there might be a good argument for making pg_proc fit the docs
>> not the other way around.  In the JSON functions, for example, pg_proc
>> randomly has some functions calling the main JSON[B] input "target"
>> while others call it "from_json" or "json_in".  I'm not real sure
>> which of those names is preferable, but inconsistency is not preferable.
>>
>>                         regards, tom lane
>>
>