MySQL Bugs: #24095: round() documentation should be clearified regarding "nearest integer"

Bug #24095	round() documentation should be clearified regarding "nearest integer"
Submitted:	8 Nov 2006 17:42	Modified:	17 Jan 2007 20:15
Reporter:	Christian Hammers (Silver Quality Contributor) (OCA)	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S4 (Feature request)
Version:	5.0	OS:
Assigned to:	Paul DuBois	CPU Architecture:	Any

Description:
In http://dev.mysql.com/doc/refman/5.0/en/mathematical-functions.html 
the round() function is described beginning with the following first sentence:
  "Returns the argument X, rounded to the nearest integer."
Most people will stop reading here as "nearest" sounds quite obvious. That, depending on the mysql version and the parameter data type the "nearest" integer to 2.5 might actually be 2.0 is counter-intuitive.

How to repeat:
read

Suggested fix:
Change first two sentences to:
  "Rounds the argument x to 0, or if specified, D decimal places."

Thank you for a reasonable documentation request.

Hello Paul

On 2007-01-12 Paul DuBois wrote:
> Hi Christian,
> 
> re:
> 
> "Rounds the argument x to 0, or if specified, D decimal places."
> 
> That looks ambiguious to me.  What does it mean?

You're right :) Better start the explanation of the round() function with:

  "Rounds the argument to D decimal places. The rounding algorithm
   depends on the type of X. D defaults to zero if not specified."

Do you think that this is clearer? 

My point was that the first sentence "Rounds to the nearest integer" is just
wrong as the first example "25E-1" is clearly not rounded to the
"nearest" integer which would be "3":
  mysql> SELECT round(25E-1), round(2.5);
  +--------------+------------+
  | round(25E-1) | round(2.5) |
  +--------------+------------+
  |            2 |          3 | 
  +--------------+------------+
(ok, technically it is of course correct as the floating point number is probably stored as something computing to 2.4999999999 but the user should
better be encouraged to continue reading all of the documentation :))

bye,

-christian-

Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.

Yes, that's clearer. Thanks.  I'll make the change.