PhpDocs: можно ли связать метод в описании параметра?

Question

Можно ли ссылаться на другой метод / класс / свойство / и т.д. внутри моего проекта внутри @deprecated тег? Как это:

/**
 * 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

Согласно PHPdoc.org, вы можете использовать для этого тег @see.

 /**
 * @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()
{
     <...>
}

Также PHPdoc.org рекомендует использовать @see в случае использования метода @deprecated:

РЕКОМЕНДУЕТСЯ (но не обязательна) предоставить дополнительное описание, указывающее, почему связанный элемент устарел. Если он заменен другим методом, РЕКОМЕНДУЕТСЯ добавить тег @see в том же PHPDoc, указывающий на новый элемент.

Answer 2

ТЛ;ДР

• PHPStorm проверен:

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

---

• vscode(inelephense) теперь поддерживает только отдельные и классовые (все еще открытая проблема ) – обходной путь:

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

«Наведение», похоже, все еще имеет ошибку (1) (2), но нажатие на отдельную ссылку FQN @see в классе работает.

---

---

Используйте полное доменное имя

У тебя это почти получилось! Но вам необходимо добавить к методу префикс, по крайней мере, имени класса (и пространства имен), круглые скобки метода не являются обязательными.

Я настоятельно рекомендую использовать FQN (полное имя) (включая пространство имен).
Это не то self::не работает, но с помощью FQN вы значительно повысите читабельность для посторонних, особенно если новый метод принадлежит другому классу.
Если вы по-прежнему не хотите использовать полные доменные имена, хотя бы укажите имя класса явно.

Круглые скобки метода не являются обязательными. (отдельный)@seeкажется, более поддерживается перекрестная IDE.