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

Question

I just wrote a function like this

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

but when making docblock, I realized that @return \React\Promise\ExtendedPromiseInterface is very generic and doesn't really help client understand what returns are to be expected in case of rejection or fulfillment.

Is there some established convention for documenting which values or exception are expected as a result of this function so that the client could chain on this function by looking at the interface only?

score 0 · Answer 1 · answered Jun 20 '16 at 15:32

0

For exceptions you can add:

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

You could add as many of these as you like too. After the @return you can add a type before and a short description of what it is after.

answered Jun 20 '16 at 15:32

Ben Rhys-Lewis

3,118
8
34
45

Thanks for your answer but I don't think this would be a good solution because it's possible to have both exceptions and promises in the same function. – Eugene Jun 22 '16 at 14:03

score 0 · Accepted Answer · answered Jun 23 '16 at 14:09

Not having found anything, I ended up making this up

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

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

2 Answers2