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?

Answer 1

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