Doc #63568 [Opn->Csd]: round() $mode parameter not explained

Edit report at https://bugs.php.net/bug.php?id=63568&edit=1 ID: 63568 Updated by: googleguy@php.net Reported by: matteosistisette at gmail dot com Summary: round() $mode parameter not explained -Status: Open +Status: Closed Type: Documentation Problem Package: Documentation problem PHP Version: Irrelevant -Assigned To: +Assigned To: googleguy Block user comment: N Private report: N New Comment: This bug has been fixed in the documentation's XML sources. Since the online and downloadable versions of the documentation need some time to get updated, we would like to ask you to be a bit patient. Thank you for the report, and for helping us make our documentation better. Previous Comments: ------------------------------------------------------------------------ [2012-12-02 07:16:47] googleguy@php.net Automatic comment from SVN on behalf of googleguy Revision: http://svn.php.net/viewvc/?view=revision&revision=328606 Log: Added description for mode constants and an example to clarify further on the behavior of the different modes. Fixes bug #63568. ------------------------------------------------------------------------ [2012-11-22 01:14:01] matteosistisette at gmail dot com > 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 ------------------------------------------------------------------------ [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