Align PSR-19 @method signatures with PHP7 with regard to return types

[rquadling]

Originally : https://github.com/php-fig/fig-standards/pull/899

Currently, the placement of the return type does not match that of PHP7.

For a new developer, this would seem 'wrong' as there are now 2 different signatures for methods.

In addition, allows for the documentation to support static methods that are processed by __callStatic().

And finally, this change removes the ambiguity where a method may be one of two;

<?php

class Parent
{
    public function __call()
    {

    }

    public static function __callStatic()
    {

    }
}

/**
 * @method static getString()
 */
class Child extends Parent
{
    <...>
}

Is getString() a static method returning void, or a regular method returning a static instance?

By having the scope and return type separated, the ambiguity is removed.

[WinterSilence]

I think need use traditional style i.e. base on @property-read, @property-write tags, readonly property(added in PHP 8.1) can be declared as @property-readonly and static method as @method-static.

[WinterSilence]

Unfortunately, none of the variant allows declare link/alias in @method i.e. specify a method of another class without parameters and return type:

class A
{
    public static function run(array $options)
    {
        <...>
    }
}
/**
 * @method A::run()
 * or
 * @method run() aliasOf A::run()
 */
class B
{
    public static function __callStatic(string $name, array $arguments)
    {
         if ($name === 'run') {
             return A::(...$arguments);
         }
         throw new RuntimeException('...');
    }
}

This would solve the problem of obsolescence: if we set returning type for A::run(), then need update @method tag for all classes calling A::run() as magic method.

[ashnazg]

Do any of the tag tokenizing applications (phpstorm, phpstan, psalm) use or allow this notation? We need to remember that this effort is to standardize on what's in use, not generate a new standard that they all must bend to.

[ondrejmirtes]

I don't think it's a good idea to make such a change now. The @method annotation has been in wide use for many years - you're not asking for a change, you're asking everyone to support both formats at once. It's not guaranteed this would gain any traction.

AFAIK this suggestion also makes it incompatible with the current format, as parsers in @method [static] [name]([type] [parameter], [...])[: return type] [description] would consume the entired end [: return type] [description] as description.

[rquadling]

Considering the return type itself is of a known format ...

: type Single type
: type1 | type2 Union type

I disagree that upgrading the parser to support union types would be that much effort.

No more than

@method type1 | type2 name()

is difficult.

The usage of : to act as the trigger for return types and | for union type and [:space:] as the separator between type(s) and description (just like [:space:] is the separator between type(s) and name at the moment) ... doesn't feel particularly complex.

[rquadling]

I have also raised this issue with JetBrains several years ago : https://youtrack.jetbrains.com/issue/WI-42107

[ashnazg]

@rquadling , I think I'm with @jaapio in that the additions for keywords like static could fit the scope of this effort... though I also agree with him and @ondrejmirtes both that it's too ingrained to move the location of the type placeholder in the syntax.

Closing this, but submit a new PR with just the keyword additions if you're game. If not, we'll probably separately get around to adding it.

I do thank you for the effort though... I follow your reasoning for this... I just can't see us dictating a big change over historical usage.