phpDocumentor - 對其他元素的評論引用是否需要完全合格的路徑？

Question

從documentation我無法真正解釋這個問題的明確答案。

例如，在@see或@param註釋中添加對另一個結構元素的引用時，是否始終需要使用該元素的完全限定名稱，即使這兩個元素彼此是局部的？

例如對象層次結構

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

比方說我想引用Dog的Cat類。由於它們駐留在相同的命名空間內，我是否需要提供完全合格的路徑？如果無論如何不重要，是否有最佳做法？無論如何，我是否應該使用完全合格的路徑，以消除開發人員閱讀代碼時出現的任何歧義或誤解？

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），或者如果 存在於名稱空間中的本地名稱。

的phpDocumentor只需要對該類類型應記錄：

@param

如果返回類型是由phpDocumentor的， 然後該類的文檔的鏈接記錄類被提供。

Answer 2

如果在命名空間聲明下有一個use語句，則不需要全限定路徑。

另外，還有一件事。在你的例子中，Animals \ Mammals \ Dog和Animals \ Mammals \ Cat在同一個命名空間中，所以你不需要任何使用語句，並且可以直接訪問Dog。