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

Question

[driverx18]

Собственно вопрос, с появлением php 7+ мы можем указывать в методе тип передаваемых данных и тип возвращаемого значения, имеет ли смысл документировать такой метод:

public function getByUserId(int $userId): Post
    {
...
    }

чтобы это по итогу выглядело так:

/**
     * @param int $userId
     * @return Post
     */
    public function getByUserId(int $userId): Post
    {
    }

как по мне в подобных методах это будет излишне, но возможно кто то использует, и может объяснить зачем нужна документация таких методов. Я не говорю про кейсы, где нужно описать что делает конкретный метод для разработчика, а речь про методы, в которых по названию все и так понятно, и по передаваемым данным/возвращаемому значению

Comments

[Adamos]

Разве что ваша IDE будет творить эту энтропию за вас.

Answer 1

[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
{
}

Answer 2

[pantsarny]

Если тайп хинтинга хватает
Если структура возвращаемого массива не интересует
Если не используется рефлексия по пхпдок
Если не генерируется документация из пхпдок
Другие если
То тогда нет смысла

Answer 3

[Дмитрий Гординский]

В описаниях кейсах смысла такого документирования нет.

Другое дело что всё еще есть достаточно других кейсов когда сигнатуру метода одними лишь средствами PHP не описать, и для единообразия в рамках проекта может требоваться документировать все.

Answer 4

[dmitriy]

есть смысл если Вы используете генерацию документации