phpDocumentor - Les références à d'autres éléments nécessitent-elles un chemin qualifié complet?

Question

Je ne pouvais pas vraiment interpréter une réponse claire à ce sujet de documentation. Lorsque vous ajoutez une référence à un autre élément structurel dans un commentaire @see ou @param, par exemple, dois-je toujours utiliser le nom complet de l'élément, même si les deux éléments sont locaux l'un par rapport à l'autre?

par exemple. Hiérarchie d'objet

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

Disons que dans la classe Cat, je veux faire référence à Dog. Comme ils résident dans le même espace de noms, dois-je donner le chemin complet? Si cela n'a pas d'importance, y a-t-il une meilleure pratique? Dois-je quand même utiliser le chemin qualifié complet pour supprimer toute ambiguïté ou malentendu des développeurs lisant le code?

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

Non, ce n'est pas nécessaire.

Definition of a ‘Type’

Un nom de classe valide vu du contexte dans lequel ce type est mentionné. Ainsi, il peut s'agir d'un nom de classe entièrement qualifié (FQCN) ou si présente dans un espace de noms un nom local.

phpDocumentor n'a besoin que ce type de classe doit être documentée:

@param

Si le type de retour est une classe qui est documentée par phpDocumentor, alors un lien vers cette classe documentation est fourni.

Answer 2

Si vous avez une instruction d'utilisation sous votre déclaration d'espace de nom, vous n'avez pas besoin du chemin qualifié complet.

Encore une chose. Dans votre exemple, Animals \ Mammals \ Dog est dans le même espace de noms que Animals \ Mammals \ Cat, donc vous n'avez besoin d'aucune instruction use et pouvez accéder directement à Dog.