Allow method tag return type to be by reference

[jaapio]

Like normal methods the method tag might return by reference. This fix introduces the support of reference return types. However in a real world implementation it not very likely one would ever mix reference return types with none reference return types. If even possible using php __call.

fixes #158

[jaapio]

@ondrejmirtes before I invest more time to improve this PR, would you merge this feature or is it not a valid case for phpstan? It would force me to find another solution on my side, but that's somehow okish.

[ondrejmirtes]

@jaapio Hi, I'm pretty sceptical about this. I don't think that PHPStan would use this information in any way (that a method returns by reference). How do you think it'd enhance the analysis?

Also, what about just reading whether __call returns by reference, instead of changing the @method syntax?

[jaapio]

I think from an analysis point of view, you could still read __call. But as a consumer of the parser not being phpstan, it makes sense, as the class containing the @method does not have to contain the implementation of __call.

In case of phpstan the return type being a & makes sense, because a method will have side effects in that case. So you could warn people about mixing @method with and without return type by reference. The only way to know that if they added it by intention to @method.

[ondrejmirtes]

I’m sorry, that doesn’t sound that exciting, unless you have a bug that’d be prevented with this in mind 😊