phpdoc how to document @return for both success and fail

Question

i'm trying to keep my php rest server properly documents, so i was wondering how do we document that the return value can be one of 2 ?

  /**
   * send email to a user that contain reset data
   * it also create reset token, so if there was an old reset token it will be changed
   *
   * @param email $email {@type email"
   * @return SuccessMessage|FailMessage
   */
  public function getSearch($email){
   // search for $email, if success return 
   if($this->doOperation()===true){
     return new SuccessMessage($email);
   }

   return new FailMessage($email);
  }

nowing that both FailMessage and SuccessMessage are just empty classes to act as a consistent data structure

something more like this.

class FailMessage extends Messages{
  function __construct(string $message, int $uid) {
      if(is_callable("parent::__construct")){
        parent::__construct(...func_get_args());
      }
      $this->uid = $uid;
      $this->message = $data;
   }
}

I see nothing wrong in `SuccessMessage|FailMessage`. What exact problem are you facing? Are you generating HTML documentation or just expecting code intelligence in your IDE? — Álvaro González, Jun 21 '17 at 10:54
I'd use `@return Message` since _both are just empty classes_ — Alex Blex, Jun 21 '17 at 11:00
yes i use generators to generate html documentation (Swagger) using luracast restler framework — Zalaboza, Jun 21 '17 at 11:01
I'm curios about `parent::__construct(...func_get_args())`. Can you actually use that to pass along all arguments to another method? I thought that `...` only was for accepting an unknown set of arguments? — M. Eriksson, Jun 21 '17 at 11:06
@MagnusEriksson yeap you can use spread operator `...` to pass all arguments to parent with exact same order as recived — Zalaboza, Jun 21 '17 at 11:13

score 2 · Answer 1 · answered Jun 21 '17 at 10:59

  /**
   * send email to a user that contain reset data
   * it also create reset token, so if there was an old reset token it will be changed
   *
   * @param email $email {@type email"
   * @return object SuccessMessage|FailMessage
   */

Your own comment is Ok but for more you can add object type. Also read the following document from the official website:

returnTags-PHPDoc

phpdoc how to document @return for both success and fail

1 Answers1