PHP 是否有在函数文档块中描述 Promise returns 的约定

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 非常笼统，并不能真正帮助客户理解 returns 在被拒绝或履行的情况下的预期结果。

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

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

PHP 是否有在函数文档块中描述 Promise returns 的约定

Does PHP have a convention for describing Promise returns in function docblock

php

documentation

docblocks

promise