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: mail+php at requinix dot net 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. 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 Previous Comments: ------------------------------------------------------------------------ [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