ドキュメンテーションのエラータグ

Question

私はエラーを引き起こしているクラスにメソッドを持っています。私は私は本当に/したいと、ここでは例外をスローしたくない

/** 
* Get info 
* @return string|FALSE Info 
*/ 
public function getInfo() 
{ 
    if ($this->info) { 
     return $this->info; 
    } 

    trigger_error('Missing info', E_USER_WARNING); 
    return FALSE; 
} 

は実行を継続するために、このコードが必要です。他の場所では、このエラーがログに記録され、ロギングエラーはこのクラスの範囲外です。

これをどのように文書化すればよいですか？例外として、私は次のものを使用します：

/** 
* @throws Exception 
*/ 

何か似たようなエラーがありますか？他の開発者が私のコードで何が起こっているのかを簡単に知りたいと思っています。

Answer 1

ここでコーディングアプローチを変更することに同意しますが、直接質問おそらく@内部タグを使用して、の開発者が知りたいと思うことを説明します。このコードに対してphpDocumentorを実行すると、--parse-privateランタイムオプションを使用しない限り、@internalタグは生成されたドキュメントに表示されません...これはinternal-info-for-devsがオフであると推定されるためです"@access private"のような消費者/ APIに興味のある読者には限界があります。

Answer 2

エラーのためのphpdocタグはありません。

trigger_error()はboolを返します。したがって、あなたのメソッドは何も返さないか、何も投げていません。あなたのエラーハンドラがそれを防ぐことができないかぎり、実行が再開されるので、@returnや@throwsを使うことはそれらを悪用し、おそらくあなたのコードを読んでいる人に混乱させるでしょう。

---

私は別の方法を使用します。

/** 
* Has info 
* 
* @return bool Whether info is available 
*/ 
public function hasInfo() 
{ 
    return (bool) $this->info; // or use isset() or whatever you need 
} 

/** 
* Get info 
* 
* @throws Exception 
* @return string The info string 
*/ 
public function getInfo() 
{ 
    if (! $this->hasInfo()) { 
     throw new Exception('Missing info'); 
    } 

    return $this->info; 
} 

してから他のコードから、あなたが行うことができます：

これは、私はそれを行うだろうかある

if ($object->hasInfo()) { 
    $info = $object->getInfo(); 
} else { 
    // no info! 
} 

私も私のコードベースのルートで例外をキャッチします。

try { 
    MyApp::run(); 
} 
catch(Exception $e) { 
    // handle error, eg. display fatal error message 
}