PHP是否有在函数docblock中描述承诺返回的约定

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

  /**
   * 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

非常通用，并不能真正帮助客户理解在拒绝或履行时预期的回报

---

是否有一些既定惯例，用于记录此函数预期的值或异常，以便客户端仅通过查看接口就可以链接到此函数？

对于异常，您可以添加：

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

---

你也可以随意添加这些。在

@return

之后，您可以添加前面的类型和后面的简短描述。

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

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

---

没有发现任何东西，我最终编造了这个

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

---

谢谢你的回答，但我认为这不是一个好的解决方案，因为在同一个函数中可能同时存在例外和承诺。谢谢你的回答，但我认为这不是一个好的解决方案，因为在同一个函数中可能同时存在例外和承诺。