PhpDocs: Link to another method in "@deprecated" tag's description?

Question

Is it possible to link to another method/class/property/etc. inside my project inline inside the @deprecated tag? Like this:

/**
 * Method description
 * @deprecated 1.0 Reason for deprecation, use {@link newMethod()} instead!
 * @param string $str
 * @param string|null $str2
 * @return bool
*/
public function method($str, $str2) {
    // TODO: Code...
}

...

?

Answer 1

According to PHPdoc.org, you could use the @see tag for that.

 /**
 * @see http://example.com/my/bar Documentation of Foo.
 * @see MyClass::$items           For the property whose items are counted.
 * @see MyClass::setItems()       To set the items for this collection.
 *
 * @return integer Indicates the number of items.
 */
function count()
{
     <...>
}

Also, PHPdoc.org recommends to use @see in case of a @deprecated method:

It is RECOMMENDED (but not required) to provide an additional description stating why the associated element is deprecated. If it is superceded by another method it is RECOMMENDED to add a @see tag in the same PHPDoc pointing to the new element.

But @see is not always required, for example "Link to another method in @param tag's description?"

Answer 2

TL;DR

• PHPStorm verified:

    /**
     * @deprecated Instead use: {@see \Your\Namespace\YourClass::yourmethod}
     */

---

• vscode(intelephense) now only supports separate @see and class (still an open issue) - workaround:

    /**
     * @deprecated Consider using {@see \Your\Namespace\YourClass::yourmethod}
     * @see \Your\Namespace\YourClass ::yourmethod
     */

The "hover" seems to be still bugged (1) (2), but clicking on separate FQN @see link in the class works.

---

---

Use FQN

You almost had it! But you have to prefix the method with at least the class name (and namespace), method parenthesis are optional.

I strongly recommend to use FQN(fully qualified name) (include the namespace).
It's not that self:: doesn't work, but with FQN, you will greatly increase readability for outsiders, especially if the new method is from a different class.
If you still don't want to use FQNs, at least use the class name explicitly.

Method parenthesis are optional. (separate) @see seems to be more cross-IDE supported.