Я не мог толковать четкий ответ об этом от документация.
При добавлении ссылки на другой структурный элемент в @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)
{
// ...
}
}
Нет, это не обязательно.
Допустимое имя класса, видимое из контекста, где упоминается этот тип.
Таким образом, это может быть либо полностью определенное имя класса (FQCN), либо
представить в пространстве имен локальное имя.
phpDocumentor нужно только, чтобы этот тип класса был задокументирован:
Если возвращаемый тип является классом, который задокументирован phpDocumentor,
затем предоставляется ссылка на документацию этого класса.
Если у вас есть оператор использования в объявлении пространства имен, вам не нужен полный путь.
Кроме того, еще одна вещь. В вашем примере Animals \ Mammals \ Dog находится в том же пространстве имен, что и Animals \ Mammals \ Cat, поэтому вам не нужно использовать оператор use и вы можете напрямую обращаться к Dog.