Can I use a @see on a @method row in PHPDoc?

Question

When using PHPs __call to make a class extend 2 classes, you can use @method to make the IDE know that the methods exists.

But when asking the IDE to jump to the declaration of the method, you end up on the @method-row, one way to not get stuck there is to add an @see row above or below. But adding that row and an separator row, makes the PHPDoc 3 times as long/high.

Is it possible to add the @see on the same row?

Seen some examples using it as it is, and some other using it inside {}. Tested it in my IDE (PhpStorm), and the jump to declaration of the @see only works if its on a separate row.

Is PHPDoc allowing us to use a @see on the same row as @method? If so, what's the correct syntax?

Example:

<?php
class a { function ma() { return "a"; } }
class b { function mb() { return "b"; } }

/**
 * Class c
 *
 * @method string mb() { @see b::mb() }
 */
class c extends a
{
    /** @var b b */
    public $b;

    function __construct() { $this->b = new b(); }
    function mc() { return "c"; }

    function __call($name, $arguments)
    {
        return call_user_func_array([$this->b, $name], $arguments);
    }
}

$c = new c();
var_dump($c->mb());

Answer 1

PHPDoc doesn't yet have a formal standard. PHPDocumentor is the de facto standard but PHP FIG is working on one too.

From the PHPStorm docs:

In PHPDoc comments, PhpStorm supports formatting options in compliance with ZEND, PEAR, and other standards.

As you and I have both discovered it takes trial and error to figure out exactly what PHPStorm supports.

PHPDocumentor does support @see inline:

Structural Elements, or inline text in a long description, tagged with the @see tag will show a link in their description.

PHP FIG's proposed standard states:

Specific Tags MAY have an "Inline PHPDoc" section at the end of the "Tag" definition... An example is the @method tag. This tag can be augmented using an "Inline PHPDoc" to provide additional information regarding the parameters, return value or any other tag supported by functions and methods.

Oddly the @method definition does not make this explicit.

I would take all this to mean you can use a @see on a @method row in PHPDoc comments, but don't expect PHPStorm to recognize it yet. Your syntax is correct and according to the "standards" it should remain at the end of the @method.