Doc #52778 [Bgs]: array_walk() doc contradicts itself

Edit report at http://bugs.php.net/bug.php?id=52778&edit=1 ID: 52778 User updated by: daniel at danielnorton dot com Reported by: daniel at danielnorton dot com Summary: array_walk() doc contradicts itself Status: Bogus Type: Documentation Problem Package: Documentation problem PHP Version: 5.3.3 Block user comment: N New Comment: I am reading the phrase as written, even if not as you are reading it. Given your interpretation, I should perhaps describe the problem as an ambiguity rather than as a contradiction. We can each read different meanings because the writing is ambiguous, and it is ambiguous in two ways: 1) For elements (in the note box): A "change" to an element can include a change such as this: unset($my_array[10]); The more specific meaning that you apparently infer is that "changes" refers *only* to an element's *contents*. 2) For the array (below the note box): Just as with an element, a "change" to an array "itself" *can* include its content, but you are apparently inferring that it *excludes* changes to its content. Perhaps you are reading "itself" to mean "its structure", but there is no such specific (or general) meaning of "itself". Both inferences are reasonable. The resolution to this issue requires resolving these ambiguities. The documentation should read "change to its content" where it means only "change to its content", and "change to its structure" where it means only "change to its structure". Previous Comments: ------------------------------------------------------------------------ [2010-09-05 05:34:45] cataphract@php.net You're not reading the whole phrase. It says "Users may not change the array itself from the callback function. e.g. Add/delete elements, unset elements, etc.". It does not contradict the note before. The note before is about changing the array data (the values), what's not possible is to change the array itself (i.e., its structure). ------------------------------------------------------------------------ [2010-09-05 01:53:44] daniel at danielnorton dot com Description: ------------ Here: http://php.net/manual/en/function.array-walk.php For the funcname parameter it mentions in a note box that specifying a parameter as a reference can be useful because "any changes made to those elements will be made in the original array itself". After the box, the description of the parameter continues with a contradictory warning: "Users may not change the array itself from the callback function." Specifying a reference is useful to save memory for large arrays, but the reason given is wrong and misleading. You should also probably take the opportunity to clarify that the reference must be in the callback function formal parameter list and not the actual parameter list of the invocation, as the latter is deprecated in PHP 5.3.0. ------------------------------------------------------------------------ -- Edit this bug report at http://bugs.php.net/bug.php?id=52778&edit=1