Support for a proposal on a change to @method docblock signatures

[rquadling]

Feature request

There is a pull request (php-fig/fig-standards#1272) to the PHP-Fig Standards (specifically PSR-19), relating to Docblock annotations for @method.

Recently, the PHP Documentation was upgraded to generate method signatures that are much closer to the code a developer would write, especially with regards to the placement of the return type.

The proposal on the PHP-Fig Standards site is to do a similar upgrade to the method signatures for @method docblock annotations.

One comment that's been raised is the level of support for such a change within the various tools that would process these annotations.

So, firstly, this I've created this issue to raise awareness of the proposal and to kindly ask if it would be possible to comment on the amount of effort required to support the proposal within PSalm.

[psalm-github-bot]

Hey @rquadling, can you reproduce the issue on https://psalm.dev ?

[orklah]

I hate the current syntax with a passion. The static as a method AND as a return type is so not obvious to me, I already forgot how Psalm interpret it.

What I hate in it is the ambiguity. Namely the current syntax allow to have a return type or not and a method can be static or not so you have to map out every possibility and then interpret the meaning of each one.

So I really do like the proposal at face value and I would have liked to be that way from the start

However, as Ondrej said in the PR, @method is installed for good. Static analyzer will have to support the current syntax for decades still (there are still project in PHP 5.4 being analyzed with Psalm for example, so imagine the state of the dependencies in those projects, it's easy to imagine current versions of dependencies will still be used many years in the future).

Which means any change to the current syntax has to be backward compatible(in the sense that there must be a way to parse both), This would add to the pile and create more things to hate for me. Namely, it would create yet another location to put return types (or to not put it sometimes, so any : in the description become ambiguous.)

Short of completely switching annotation, I don't have a suggestion to make the situation better...

[AndrolGenhald]

Does the current syntax allow description with no whitespace (eg @method void myMethod(int $foo)description goes here)? If not, I would think the : would remove the ambiguity for the most part (as long as it's clear there can be no whitespace between the ) and :). There's still the ambiguity for static, but I think if we say the [static] in front of the method is considered a return type unless a return type is later specified like : void it's probably fine (assuming that's the current behavior, I don't know either...).

I think it would also be nice to correctly parse whitespace in templates and parentheses (eg for Psalm's conditional return types), that way : array<int, string> parses with array<int, string> as the return type instead of array<int, as the return type and string> as the description.

Something like:
@method [static or return type] [name]([type] [parameter], [...])[: return type] [description]
This regexp is approximately accurate, although it can't handle nested parentheses or templates.

Multiple line return types might also be useful for array shapes, but that's probably never going to happen (or if it does it'll probably be Psalm specific).