Codification for "in/out" (referenced) parameter

[zeleznypa]

Please add codification into the PSR-5 documentation about @param, how to declare "in/out" parameter.

For somebody who look at documentation it could be useful to know, that parameter is "in/out".

/**
 * @param string|null &$foo
 */
public function foo(?string &foo) {
   //...
}

[zeleznypa]

Unfortunately authors of otherwise quite good PhpStan won't to fix the bug in their implementation of phpdoc grammar until the formal codification of this use case. :(

Issue in official phpDoc documentation was also crated

[zeleznypa]

@JanTvrdik have true, when he said in the Czech discussion that there is a problem in difference between in/out and just out parameter.

Question is, if it is necessary to specify this difference or isn't it enough to be informed, that the parameter is given by reference in any meaning.

[ashnazg]

I don't remember phpDocumentor ever disallowing this, at least not 1.x... @mvriel @jaapio , is 2.x/3.x not allowing & currently?

[jaapio]

I need to check that with the latest release. But I don't see any problems with this from our side. Except that I am sure that it isn't handled as a special type. So we won't render it in a specific way.

However @OndrejMirtes mentioned that phpstan gives an error on this by purpose. I don't know what he means from a phpstan perspective. I can imagine that they added a feature that does not allow this notation.

[ondrejmirtes]

Hi, PHPStan simply does not see this as a valid syntax, Type must be followed by the variable name, including $. The information is already in the PHP code. This syntax isn't codified anywhere so someone should decide what to do about it and what should be the standard (if the & must be part of the phpDoc or not).

[jaapio]

I agree with you that it is redundant information that can be extracted from the source code.

I think we can just leave it as is. The documentation should only contain the information needed to identify the parameters. We should check how variadict variables are handled in the param definition. It feels wrong to have that in and the byref operator not.

[TysonAndre]

Phan permits an optional & before the $ of the parameter name in PHPDoc, and currently ignores it.

---

On an unrelated note, it may be useful to provide a standardized way to distinguish between reference parameters that are modified and reference parameters that are ignored and overwritten.

• This is done in Phan with https://github.com/phan/phan/wiki/Annotating-Your-Source-Code#phan-output-reference - If this is ever included, the phpdoc syntax would probably be different
• This isn't urgent

[neuro159]

PhpStorm will accept but ignore & in PhpDoc and will not generate it.

[ashnazg]

Ok, let me step back a minute...

The code signature itself is going to have the & on it (string ?$foo)...

The question is about the variable name listed in the @param tag... whether or not the & portion is disallowed vs allowed vs required.

Coming from my phpDocumentor 1.x days, I'd lean towards required, so that it perfectly matches the variable name in the code signature. Also, I do remember personally looking for &$foo in the generated docs to remember if it was a reference being passed. Whether or not we wanted to prescribe any additional doc behavior in this scenario, I would prefer to at least keep the ability for the &$ to stand out.

...

Am I hearing from others that they strip it when they see it, ignore it, and don't show it to anyone in docs/popups? Thus, there's nothing in particular in the displayed docs to show you it's a reference? So unless you are looking directly at the code and its signature, you'll have no idea the reference is in there?

[JanTvrdik]

Long Version

1) If we make writing & in @param tags required for all parameters that are passed-by-reference (i.e. emit error in case it's not explicitly specified) we create a massive BC break, as most code is not written like this.
Also & does provide very little information about how the passed-by-reference parameter is used. If you actually wanted to document something useful, you'll need to introduce way to declare whether the parameter is in, inout or out (or sth like that) and if it's inout or out then you'll also need a way to declare the output type (to confusion of many, the type in signature is an input type and does not restrict the output type in any way).

2) If we make writing & in @param tags optional for all parameters that are passed-by-reference, then nobody can rely on the @param tag alone as you must always also check the signature.

3) If we make writing & in @param tags disallowed for all parameters that are passed-by-reference, we create a smaller BC break and everybody must check the signature, which is (unlike phpdoc) guaranteed to always be correct.

---

Short Version

1) required → large BC break, and information may be incorrect 2) optional → no BC break, information is totally unreliable 3) disallowed → small BC break, information guaranteed to be correct

[ashnazg]

@zeleznypa , if you wish to pursue this further, please bring this up as a new thread on the FIG mailing list for discussion -- https://groups.google.com/forum/#!forum/php-fig