php - PHP 是否有在函数 docblock 中描述 Promise 返回的约定

Question

我刚刚写了一个这样的函数

  /**
   * Send an asynchronous GET request
   *
   * @param string $url
   * @param array  $options
   *
   * @return \React\Promise\ExtendedPromiseInterface
   */
  public function getAsync( $url, array $options = [] );

但是在制作 docblock 时，我意识到这@return \React\Promise\ExtendedPromiseInterface是非常通用的，并不能真正帮助客户了解在拒绝或履行的情况下预期的回报。

是否有一些既定的约定来记录该函数的预期值或异常，以便客户端可以通过仅查看接口来链接该函数？

Answer 1

对于例外情况，您可以添加：

/**
 * @throws customException if the bad thing happens
 */

您也可以根据需要添加任意数量的这些。之后，@return您可以添加之前的类型和之后的内容的简短描述。

Answer 2

没有找到任何东西，我最终弥补了这个

  /**
   * 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 = [] );