Bug #69011 [Wfx->Nab]: contraddiction in echo documentation

Edit report at https://bugs.php.net/bug.php?id=69011&edit=1 ID: 69011 Updated by: salathe@php.net Reported by: teo8976 at gmail dot com Summary: contraddiction in echo documentation -Status: Wont fix +Status: Not a bug Type: Bug -Package: Doc Build problem +Package: Documentation problem PHP Version: Irrelevant Block user comment: N Private report: N New Comment: The area of the page in question is the function description or "prototype". Its purpose is to describe the prototype of a function (in this case, echo() is a language construct but we document it in the same manner): the function prototype is not meant to be valid PHP code nor a demonstration of how to use the function. Other examples of invalid "PHP code" used in the function prototype include the leading return type declaration ("void") and the square brackets around optional arguments. More details of the different parts of a function prototype, as we display them in the documentation, are available on our "How to read a function definition (prototype)" page at http://php.net/manual/en/about.prototypes.php Finally, yes, the examples section and the textual description section could both make it more clear that parentheses are allowed for single arguments and not allowed for multiple arguments. Previous Comments: ------------------------------------------------------------------------ [2015-04-06 11:56:44] teo8976 at gmail dot com Then you should at least highlight it much more. Instead of being just an "Additionally...." phrase ending a paragraph, this should be the very first note just below the syntax and highlighted in some way. Your documentation system certainly allows you that. Also, I notice that there's a snippet of code at the end of the description. So how comes you can't add a snippet of code at the beginning showing the two usages? ------------------------------------------------------------------------ [2015-04-06 06:12:40] sobak@php.net Sorry, but this is how our documentation renderer works. It can be changed, but I doubt anyone will find the time for such an edge case. ------------------------------------------------------------------------ [2015-02-08 02:35:26] teo8976 at gmail dot com Description: ------------ --- From manual page: http://www.php.net/function.echo --- This: """ Description void echo ( string $arg1 [, string $... ] ) """ is in contraddiction with this: """ Additionally, if you want to pass more than one parameter to echo, the parameters must not be enclosed within parentheses. """ The second is true, so the first must be corrected. It should read something like: """ Description void echo ( string $arg1) void echo string $arg1 [, string $... ] """ And by the way, why on earth not changing the behavior so that it does accept parenthesis with more than one parameter?? Test script: --------------- --- From manual page: http://www.php.net/function.echo --- This: """ Description void echo ( string $arg1 [, string $... ] ) """ is in contraddiction with this: """ Additionally, if you want to pass more than one parameter to echo, the parameters must not be enclosed within parentheses. """ The second is true, so the first must be corrected. It should read something like: """ Description void echo ( string $arg1) void echo string $arg1 [, string $... ] """ And by the way, why on earth not changing the behavior so that it does accept parenthesis with more than one parameter?? Expected result: ---------------- --- From manual page: http://www.php.net/function.echo --- This: """ Description void echo ( string $arg1 [, string $... ] ) """ is in contraddiction with this: """ Additionally, if you want to pass more than one parameter to echo, the parameters must not be enclosed within parentheses. """ The second is true, so the first must be corrected. It should read something like: """ Description void echo ( string $arg1) void echo string $arg1 [, string $... ] """ And by the way, why on earth not changing the behavior so that it does accept parenthesis with more than one parameter?? Actual result: -------------- --- From manual page: http://www.php.net/function.echo --- This: """ Description void echo ( string $arg1 [, string $... ] ) """ is in contraddiction with this: """ Additionally, if you want to pass more than one parameter to echo, the parameters must not be enclosed within parentheses. """ The second is true, so the first must be corrected. It should read something like: """ Description void echo ( string $arg1) void echo string $arg1 [, string $... ] """ And by the way, why on earth not changing the behavior so that it does accept parenthesis with more than one parameter?? ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=69011&edit=1