在PhpStorm中标记@see

Question

I have the following code:

class A {

    /**
     * Splitter for words
     *
     * @var null|string
     */
    private $splitter = '-';

    /**
     * Desc...
     *
     * @param null|string $splitter   @see $splitter
     */
    function __construct(
        $splitter = null
    ) {
      // implementation
    }

}

$a = new A();

When using CTRL+Q in PhpStorm to see documentation for class constructor I will see:

null|string $splitter @see $splitter

Am I doing something wrong or should PhpStorm be configured to display description for $splitter here. I would expect here to have displayed Splitter for words or link to $splitter member and not just @see $splitter.

As I checked it doesn't matter that those 2 variables have the same name - even if constructor argument name would be $s PhpStorm still displays @see $splitter.

Answer 1

First of all: when in-lined (like you did) the PHPDoc tag should be surrounded by {}, like this: @param null|string $splitter {@see $splitter}

Secondly: PhpStorm does NOT parse additional/in-line tags in @param or @return descriptions -- it only parses it if @see is located on separate line or if in-lined in main (method) description section. In other words: in-lining in @param description will not work (very unfortunately).

In this regard PhpStorm behaves just like PhpDocumentor itself (checked using version 2.6.1).

Code:

<?php

class PHPDoc_See
{

    /**
     * Splitter for words
     *
     * @var null|string
     */
    private $splitter = '-';

    /**
     * Desc...  {@see $splitter}
     *
     * @param null|string $splitter Bla-Bla {@see $splitter}
     */
    function __construct($splitter = null)
    {
        // implementation
    }
}

PhpDocumentor result:

In this regard PhpStorm behaves a bit better -- at least it parses @see in main (method) description.

---

The only workable solution (as I see it) is to place @see tags on separate lines:

/**
 * Some Description
 *
 * @param null|string $splitter Bla-Bla
 * @see $splitter
 */

---

Of course: you can always submit Feature Request ticket to the PhpStorm's Issue Tracker (I would vote for it) .. but considering how PhpDocumentor is behaving in this regard .. I have serious doubts that PhpStorm devs will have it implemented any time soon (they do prefer following the same behaviour as referenced tool).