документация — есть ли в PHP соглашение для описания возвратов Promise в функции docblock
Я просто написал такую функцию
/**
* Send an asynchronous GET request
*
* @param string $url
* @param array $options
*
* @return \React\Promise\ExtendedPromiseInterface
*/
public function getAsync( $url, array $options = [] );
но когда делал докблок я понял что @return \React\Promise\ExtendedPromiseInterface является очень общим и на самом деле не помогает клиенту понять, какие возвраты следует ожидать в случае отклонения или выполнения.
Существует ли какое-либо установленное соглашение для документирования того, какие значения или исключения ожидаются в результате этой функции, чтобы клиент мог связать эту функцию, рассматривая только интерфейс?
Решение
Для исключений вы можете добавить:
/**
* @throws customException if the bad thing happens
*/
Вы можете добавить столько, сколько захотите. После @return Вы можете добавить тип до и краткое описание того, что это после.
Другие решения
Не найдя ничего, я придумал это
/**
* Send an asynchronous GET request
*
* @param string $url
* @param array $options
*
* @return \React\Promise\ExtendedPromiseInterface
*
* @promise.resolve \MyApp\Interfaces\ResponseInterface
* @promise.reject \MyApp\Exceptions\RequestException
*/
public function getAsync( $url, array $options = [] );