@param-out variant for both in _and_ out types

[dktapps]

Consider the following code:

	/**
	 * @phpstan-param array<int, true> $visited
	 * @phpstan-param-out array<int, true> $visited
	 */
	protected function findLog(Vector3 $pos, array &$visited = [], int $distance = 0) : bool{
		$index = World::blockHash($pos->x, $pos->y, $pos->z);
		if(isset($visited[$index])){
			return false;
		}
		$visited[$index] = true;

	        foreach(Facing::ALL as $side){
		        if($this->findLog($pos->getSide($side), $visited, $distance + 1)){
			        return true;
		        }
	        }

		return false;
	}

In this case, the "in" type and "out" type are the same, but to get the full level of detail, I have to repeat the type information twice in two different PHPDoc tags (3 if I include the standards-compliant "legacy" PHPDoc for older tools).

Is there a way to describe this with just one tag, or am I requesting a feature that doesn't exist?

[staabm]

php allows you to write any type into a variable: https://3v4l.org/bhrUp

this means the in and the out type are independent. The case you describe in which both are the same is a special case .. not sure it makes sense to introduce another phpdoc for.

but this decision is up to ondrey :)

[ondrejmirtes]

Yes, usually the types are different, it doesn't make much sense to complicate our lives with another PHPDoc tag :)

[dktapps]

Well, this case occurred in a few places in PM where references are used (about a dozen total places where @param-out was useful). See: pmmp/PocketMine-MP@2fdc46c

[dktapps]

Came back to this 6 months later after encountering the same thing again, and I'm still convinced this should be added. Almost every time I find myself using @param-out, the type is the same as was put in (e.g. an array passed by reference).

[ondrejmirtes]

I changed my mind about this. When @param-out is not present and the parameter is by-ref, the out type is going to be same as the parameter type. If you want different behaviour then you can still use @param-out for a completely different type.

See: phpstan/phpstan-src@27a952e
Also: phpstan/phpstan-src@2f55c7c