Doc #63568 [Com]: round() $mode parameter not explained
Edit report at https://bugs.php.net/bug.php?id=63568&edit=1
ID: 63568
Comment by: matteosistisette at gmail dot com
Reported by: matteosistisette at gmail dot com
Summary: round() $mode parameter not explained
Status: Open
Type: Documentation Problem
Package: Documentation problem
PHP Version: Irrelevant
Block user comment: N
Private report: N
New Comment:
> Heard you the first time.
LOL sorry, often in some bug trackers all the fields (steps to reproduce,
expected result, observed result) are required, and I seemed to remember it was
the case in this one. I didn't want to take the risk to be obliged to compute
another sum.
> Did you know you can submit changes to the online documentation?
I didn't
Previous Comments:
------------------------------------------------------------------------
[2012-11-22 00:29:29] mail+php at requinix dot net
I swear, someday I'll get a handle on those line breaks.
------------------------------------------------------------------------
[2012-11-22 00:27:56] mail+php at requinix dot net
Heard you the first time.
Did you know you can submit changes to the online documentation? Look for the [edit] link in the
top-right corner of
manual pages.
I've given a shot to a patch. Turns out to be surprisingly awkward to accurately explain the
tie-breaking problem in
a short, simple sentence. Even more so since $precision is arbitrary - and possibly negative. I also
changed the
demonstration of $mode to show how PHP_ROUND_HALF_(UP|DOWN) round relative to zero (not infinity
like one might
expect).
"round: description of the $mode constants (bug #63568)"
http://edit.php.net/?patchID=772&project=PHP
------------------------------------------------------------------------
[2012-11-20 18:19:42] matteosistisette at gmail dot com
Description:
------------
---
From manual page: http://www.php.net/function.round#refsect1-function.round-
parameters
---
mode
One of PHP_ROUND_HALF_UP, PHP_ROUND_HALF_DOWN, PHP_ROUND_HALF_EVEN, or
PHP_ROUND_HALF_ODD.
It doesn't say a word about what each mode does. There are examples but they are
insufficient. Documentation is supposed to document, not to oblige you to
infer/guess from examples. Examples are fine, but they cannot _replace_
documentation.
Test script:
---------------
---
From manual page: http://www.php.net/function.round#refsect1-function.round-parameters
---
mode
One of PHP_ROUND_HALF_UP, PHP_ROUND_HALF_DOWN, PHP_ROUND_HALF_EVEN, or PHP_ROUND_HALF_ODD.
It doesn't say a word about what each mode does. There are examples but they are insufficient.
Documentation is supposed to document, not to oblige you to infer/guess from examples. Examples are
fine, but they cannot _replace_ documentation.
Expected result:
----------------
---
From manual page: http://www.php.net/function.round#refsect1-function.round-
parameters
---
mode
One of PHP_ROUND_HALF_UP, PHP_ROUND_HALF_DOWN, PHP_ROUND_HALF_EVEN, or
PHP_ROUND_HALF_ODD.
It doesn't say a word about what each mode does. There are examples but they are
insufficient. Documentation is supposed to document, not to oblige you to
infer/guess from examples. Examples are fine, but they cannot _replace_
documentation.
Actual result:
--------------
---
From manual page: http://www.php.net/function.round#refsect1-function.round-
parameters
---
mode
One of PHP_ROUND_HALF_UP, PHP_ROUND_HALF_DOWN, PHP_ROUND_HALF_EVEN, or
PHP_ROUND_HALF_ODD.
It doesn't say a word about what each mode does. There are examples but they are
insufficient. Documentation is supposed to document, not to oblige you to
infer/guess from examples. Examples are fine, but they cannot _replace_
documentation.
------------------------------------------------------------------------
--
Edit this bug report at https://bugs.php.net/bug.php?id=63568&edit=1
Thread (5 messages)