phpDocumentor — Нужны ли для комментариев ссылки на другие элементы полный путь?

Я не мог толковать четкий ответ об этом от документация.

При добавлении ссылки на другой структурный элемент в @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)
{
// ...
}
}

0

Решение

Нет, это не обязательно.

Определение «Типа»

Допустимое имя класса, видимое из контекста, где упоминается этот тип.
Таким образом, это может быть либо полностью определенное имя класса (FQCN), либо
представить в пространстве имен локальное имя.

phpDocumentor нужно только, чтобы этот тип класса был задокументирован:

@param

Если возвращаемый тип является классом, который задокументирован phpDocumentor,
затем предоставляется ссылка на документацию этого класса.

2

Другие решения

Если у вас есть оператор использования в объявлении пространства имен, вам не нужен полный путь.

Кроме того, еще одна вещь. В вашем примере Animals \ Mammals \ Dog находится в том же пространстве имен, что и Animals \ Mammals \ Cat, поэтому вам не нужно использовать оператор use и вы можете напрямую обращаться к Dog.

1

По вопросам рекламы ammmcru@yandex.ru
Adblock
detector