Re: Re: [BUGS] BUG #14695: Documentation is not accurate

On Fri, Jun 9, 2017 at 12:59 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Well, it still looks correct to me. FWIW, you're not the first to be
> confused by this. In currently-supported releases we've rephrased it as

> ceil(dp or numeric) nearest integer greater than or equal to argument

> floor(dp or numeric) nearest integer less than or equal to argument

While I do agree that the current docs on ceil() and floor() are good, I
also think that the description of round() is really not on par with them,
since I've seen people stumble on that more than once. So maybe this is a
good opportunity to improve it.

[3] describes round() as "nearest integer", but according to [1], that
could be understood as any one of 6 deterministic plus 2 non-deterministic
methods.

In reality, the behavior is actually "half away from zero" for numeric and
"half to even" for floating point (on some machines). While this is well
documented somewhere else (last paragraph of 8.1.2 in [2]), there is no
clear link between [3] and [2] for people who who search for round().

So I think the docs on round() could be improved in one of two ways:
- copy the rounding description from [2] to [3] so people know what they
are getting when calling round(); or,
- put a link somewhere in [3] pointing towards [2] so that people can find
the related pages in one glance.

[1] https://en.wikipedia.org/wiki/Rounding#Comparison_of_rounding_modes
[2]
https://www.postgresql.org/docs/current/static/datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL
[3] https://www.postgresql.org/docs/current/static/functions-math.html
--

Arthur Nascimento - tureba