Documentation suggestion: One-line explanation of term 'pseudo-type'
| From: | Bart van der Wal | Date: | Wed, 21 Dec 2016 20:37:50 +0000 |
| Subject: | Documentation suggestion: One-line explanation of term 'pseudo-type' | ||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969386476@lists.php.net to get a copy of this message | ||
Hi all,
As mentioned in the subject I would suggest adding a oneline explanation at
the top of the page about pseudo-types:
http://php.net/manual/en/language.pseudo-types.php
Currently this page only lists all pseudo-types that are used in the docs.
I would just add a short explanation at the top. Something like:
"A pseudo-type is not an actual type or keyword you can use in PHP, but is
a term used here in the documentation to specify the types or values an
argument is expected to have."
Most of you might find this explanation obvious. But you are more initiated
into the language and documentation. But I think the documentation should
allow the unitiated to move over to the initiated.
I myself was confused by this initially when I was trying to add an
argument with type 'mixed'. But got a unspecific error message:
TypeError: Argument 1 passed to *<functionName>()* must be an instance of
mixed, stringgiven.
Then trying Google for an answer brought me to the documentation page I
mentioned, but the current description there only strengthened my
expectation that my approach SHOULD work:
*mixed* indicates that a parameter may accept multiple (but not necessarily
all) types.
I was expecting 'mixed' to be something along the lines of the 'any' type
in Typescript, as I explained in this stackoverflow question:
http://stackoverflow.com/questions/41267772/phps-mixed-type-vs-typescripts-any
And I'm not the only one who is confused as this Stackoverflow question
proofs:
http://stackoverflow.com/questions/37199403/php-7-how-to-use-mixed-parameter-type-in-my-own-functions
Can I implement the suggested change in the docs myself via a pull request
or something similar? Below this mail two related language suggestions, but
this simple change in the docz is more than sufficient for now.
Regards,
Bart
*TLDR Language suggestions*
Needlessly to say I'd love it if PHP WOULD just allow using these
pseudo-types in actual function signatures. To parafrase Arthur C .Clarke:
"Any sufficiently high level programming language is indistinguisable from
a specification." :P
Note that for instance another pseudo-type
array|object listed on the
page is very similar to an actual type specification in TypeScript using Union
types
<https://www.typescriptlang.org/docs/handbook/advanced-types.html#union-types>.
PHP 9? :)
It would also make sense to me if the current error message that is thrown
is only thrown if a type or Class 'mixed' is actually defined. If not then
this error message would make more sense and prevent confusion in my view:
TypeError: Argument 1 of *<functionName>()* specified as mixed, but no such
type or class exists.
And then refers to the line number of the function declaration or signature
instead of to where the function is called.
--
There are 10 kinds of people. Those that understand binary notation and
those that don't.