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

没有找到任何东西，我最终解决了这个问题

select count(*) from 
    (select car.year, car.month, count(car) 
     from Car car group by car.year)

PHP是否有一个约定来描述函数docblock

2 个答案: