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

Question

我无法真正从 documentation.

中解读出明确的答案

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

例如对象层次结构

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

假设在 Cat class 我想引用 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)
    {
        // ...
    }
}

Answer 1

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

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

Answer 2

不，没有必要。

Definition of a ‘Type’

A valid class name seen from the context where this type is mentioned. Thus this may be either a Fully Qualified Class Name (FQCN) or if present in a namespace a local name.

phpDocumentor 只需要记录 class 类型：

@param

If the return Type is a class that is documented by phpDocumentor, then a link to that class’ documentation is provided.

Answer 3

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

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

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

phpDocumentor - Do comment references to other elements need a fully qualified path?

php

documentation

phpdoc