php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Bug #69011 contraddiction in echo documentation
Submitted: 2015-02-08 02:35 UTC Modified: 2015-04-08 14:01 UTC
From: teo8976 at gmail dot com Assigned:
Status: Not a bug Package: Documentation problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
View Add Comment Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
You can add a comment by following this link or if you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: teo8976 at gmail dot com
New email:
PHP Version: OS:

 

 [2015-02-08 02:35 UTC] 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??

Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2015-04-06 06:12 UTC] sobak@php.net
-Status: Open +Status: Wont fix -Type: Documentation Problem +Type: Bug -Package: Documentation problem +Package: Doc Build problem
 [2015-04-06 06:12 UTC] 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-04-06 11:56 UTC] 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-08 14:01 UTC] salathe@php.net
-Status: Wont fix +Status: Not a bug -Package: Doc Build problem +Package: Documentation problem
 [2015-04-08 14:01 UTC] salathe@php.net
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.
 
PHP Copyright © 2001-2021 The PHP Group
All rights reserved.
Last updated: Sun Jan 17 04:01:23 2021 UTC