phpDocumentor - 对其他元素的注释引用是否需要完全限定的路径？答案

【问题标题】：phpDocumentor - Do comment references to other elements need a fully qualified path?phpDocumentor - 对其他元素的注释引用是否需要完全限定的路径？
【发布时间】：2017-10-23 08:00:25
【问题描述】：

我无法从documentation 那里得到明确的答案。

例如，当在@see 或@param 注释中添加对另一个结构元素的引用时，我是否总是需要使用元素的完全限定名称，即使这两个元素彼此是本地的？

例如对象层次结构

Animals
    --- Mammals
        --- Cat
        --- Dog

假设在 Cat 类中我想引用 Dog。由于它们位于同一个命名空间中，我是否需要提供完全限定的路径？如果这两种方式都没有关系，是否有最佳实践？我是否应该使用完全限定路径，以消除开发人员阅读代码的任何歧义或误解？

namespace Animals\Mammals;

class Cat
{

    /**
     * @param Dog $dog An instance of a Dog.
     *
     * OR
     *
     * @param \Animals\Mammals\Dog $dog An instance of a Dog.
     */
    public function foo(Dog $dog)
    {
        // ...
    }
}

【问题讨论】：

phpdoc.org/docs/latest/references/phpdoc/types.html

标签： php documentation phpdoc

【解决方案1】：

如果命名空间声明下有 use 语句，则不需要完全限定路径。

另外，还有一件事。在您的示例中，Animals\Mammals\Dog 与 Animals\Mammals\Cat 位于同一命名空间中，因此您不需要任何 use 语句，可以直接访问 Dog。

【讨论】：

【解决方案2】：

不，没必要。

Definition of a ‘Type’

从提及此类型的上下文中看到的有效类名。 因此，这可能是完全限定的类名 (FQCN)，或者如果在命名空间中显示本地名称。

phpDocumentor 只需要记录该类类型：

@param

如果返回类型是由 phpDocumentor 记录的类，然后提供指向该类文档的链接。

【讨论】：

【解决方案3】：

所选答案仍然有效吗？因为我在 2019 年用 PHPStorm 开始了一个项目。回到通过在方法上键入 /** 创建的 DocBlock 没有 FQCN（例如 @param Dog $dog）。与 2020 年相比，我认为有一个 PHPStorm 更新，因为突然间我的 DocBlocks 总是包含完整的 FQCN (@param \Animals\Mammals\Dog $dog)。类是否在顶部包含 use Dog; 语句并不重要！

我没有更改任何项目设置，所以我的问题是，现在使用 FQCN 的较新 IDE conciders 是最佳实践。但我找不到任何相关来源或 PSR。有人知道更多吗？

【讨论】：