@driverx18

Стоит ли использовать phpdoc для описания методов, если я использую тайпхинт и указываю возвращаемые значения?

Собственно вопрос, с появлением php 7+ мы можем указывать в методе тип передаваемых данных и тип возвращаемого значения, имеет ли смысл документировать такой метод:
public function getByUserId(int $userId): Post
    {
...
    }

чтобы это по итогу выглядело так:
/**
     * @param int $userId
     * @return Post
     */
    public function getByUserId(int $userId): Post
    {
    }


как по мне в подобных методах это будет излишне, но возможно кто то использует, и может объяснить зачем нужна документация таких методов. Я не говорю про кейсы, где нужно описать что делает конкретный метод для разработчика, а речь про методы, в которых по названию все и так понятно, и по передаваемым данным/возвращаемому значению
  • Вопрос задан
  • 239 просмотров
Решения вопроса 1
Rsa97
@Rsa97
Для правильного вопроса надо знать половину ответа
IMHO, там где понятно по тайпхинтам, смысла в phpdoc нету. А вот там где непонятно
/**
 * @return array{uid: string, name: string, isAdmin: bool}
 * @throws AuthenticationException on authentication error
 */
private static function authenticate(string $login, string $password): array
{
}
Ответ написан
Комментировать
Пригласить эксперта
Ответы на вопрос 3
@pantsarny
Если тайп хинтинга хватает
Если структура возвращаемого массива не интересует
Если не используется рефлексия по пхпдок
Если не генерируется документация из пхпдок
Другие если
То тогда нет смысла
Ответ написан
Комментировать
В описаниях кейсах смысла такого документирования нет.

Другое дело что всё еще есть достаточно других кейсов когда сигнатуру метода одними лишь средствами PHP не описать, и для единообразия в рамках проекта может требоваться документировать все.
Ответ написан
Комментировать
dmitriylanets
@dmitriylanets
веб-разработчик
есть смысл если Вы используете генерацию документации
Ответ написан
Комментировать
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы