Question

我无法从documentation真正解释这个问题的明确答案。

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

e.g。对象层次结构

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

Answer 1

不，没有必要。

Definition of a ‘Type’

从提及此类型的上下文中看到的有效类名。 因此，这可能是完全合格的类名（FQCN）或if 在名称空间中显示本地名称。

phpDocumentor只需要记录类类型：

@param

如果返回Type是phpDocumentor记录的类，然后提供了该类文档的链接。

Answer 2

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

另外，还有一件事。在您的示例中，Animals \ Mammals \ Dog与Animals \ Mammals \ Cat位于相同的名称空间中，因此您不需要任何使用声明并且可以直接访问Dog。

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

2 个答案: