php - phpdoc 成功と失敗の両方で @return を文書化する方法

Question

PHP レスト サーバーを適切に文書化しようとしているので、戻り値が 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;
   }
}