phpdoc как документировать @turn для успеха и неудачи

Question

Я пытаюсь правильно сохранить документы на своем php rest server, поэтому мне было интересно, как мы документируем, что возвращаемое значение может быть одним из 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);
  }

Теперь, когда FailMessage и SuccessMessage являются просто пустыми классами, которые действуют как согласованная структура данных

что-то вроде этого.

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;
   }
}

Answer 1

  /**
   * 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
   */

Ваш собственный комментарий хорошо, но для большего вы можете добавить тип объекта. Также прочитайте следующий документ с официального сайта:

returnTags-PHPDoc