Re: Documentation suggestion: One-line explanation of term 'pseudo-type'
| From: | Peter Cowburn | Date: | Thu, 22 Dec 2016 11:06:50 +0000 |
| Subject: | Re: Documentation suggestion: One-line explanation of term 'pseudo-type' | ||
| References: | 1 | Groups: | php.doc |
| Request: | Send a blank email to phpdoc+get-969386477@lists.php.net to get a copy of this message | ||
Hi Bart!
See my comments below.
On 21 December 2016 at 20:37, Bart van der Wal <bartvanderwal@gmail.com>
wrote:
> 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.
>
A short sentence, or two, to introduce this page would be great. Agreed.
>
> 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
>
> <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.
>
Each of the pages in the manual have an "edit" link, situated at the top
just beneath the "change language" dropdown box. This takes you to our
Online Editor, where you can make changes to the documentation source code
(which is written in Docbook XML). In your case, the link is
https://edit.php.net/?project=PHP&perm=en/language.pseudo-types.php
If you go in to the editor, make your change, and submit it as a "patch for
review". Then your change will be looked at and merged in to the manual in
due course. To speed up the process, it is a good ideal to send an email to
this list saying that you have a patch ready to be reviewed.
>
> 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.
>