php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login

go to bug id or search bugs for

Doc Bug #63568 round() $mode parameter not explained
Submitted: 2012-11-20 18:19 UTC Modified: 2012-12-02 07:17 UTC
From: matteosistisette at gmail dot com Assigned: googleguy (profile)
Status: Closed Package: Documentation problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
View Developer Edit
 [2012-11-20 18:19 UTC] 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.

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2012-11-22 00:27 UTC] 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-22 00:29 UTC] mail+php at requinix dot net 
I swear, someday I'll get a handle on those line breaks.
 [2012-11-22 01:14 UTC] 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-12-02 07:16 UTC] 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-12-02 07:17 UTC] googleguy@php.net
-Status: Open +Status: Closed -Assigned To: +Assigned To: googleguy
 [2012-12-02 07:17 UTC] googleguy@php.net 
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.
 
PHP Copyright © 2001-2026 The PHP Group
All rights reserved. 		Last updated: Tue Oct 06 11:00:02 2026 UTC