PHP是否有一个可以描述功能模块中的承诺回报的约定

Question

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

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

但是，在制作DocBlock时，我意识到@return ReactPromiseExtendedPromiseInterface非常通用，并且并不能真正帮助客户理解在拒绝或履行的情况下可以期待什么回报。

是否有一些已建立的约定，以记录由于此功能而预期的值或异常，以便客户可以通过仅查看接口来链接此功能？

Answer 1

对于例外，您可以添加：

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

您也可以添加尽可能多的其中。@return之后，您可以在此之前添加类型和简短描述。

Answer 2

尚未找到任何东西，我最终做了这个

  /**
   * Send an asynchronous GET request
   * 
   * @param string $url
   * @param array  $options
   *
   * @return ReactPromiseExtendedPromiseInterface
   *
   * @promise.resolve MyAppInterfacesResponseInterface
   * @promise.reject  MyAppExceptionsRequestException
   */
  public function getAsync( $url, array $options = [] );