PhpDocs：链接到“@deprecated”标签描述中的另一个方法？

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 建议在 @deprecated 方法的情况下使用 @see :

建议（但不要求）提供附加说明，说明相关元素为何被弃用。如果它被其他方法取代，建议在指向新元素的同一个 PHPDoc 中添加 @see 标签。

但是

@see

并不总是必需的，例如“链接到@param标签描述中的另一个方法？”

Answer 2

TL；博士

• PHPStorm 已验证：

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

---

• vscode(intelephense) 现在仅支持单独的

  @see

  和类（仍然是一个悬而未决的问题） - 解决方法：

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

“悬停”似乎仍然有问题 (1) (2)，但单击课程中单独的 FQN @see 链接是有效的。

---

---

使用 FQN

你几乎已经拥有它了！但你必须在方法前面至少加上类名（和命名空间），方法括号是可选的。

我强烈建议使用FQN（完全限定名称）（包括命名空间）。
并不是说

self::

不起作用，而是使用FQN，您将极大地提高对外人的可读性，特别是如果新方法来自不同的类。
如果您仍然不想使用 FQN，至少显式使用类名。

方法括号是可选的。 （单独）

@see

似乎更支持跨IDE。