例外はいつ文書化する必要がありますか？

Question

次のスニペットと仮定します。dependency::bar()場合

public function foo() 
{ 
    return $this->dependency->bar(); 
} 

は、例外をスローすることが知られているが、foo()はそれを処理することが期待されていません。 foo()には@throwsのエントリがありますか？それとも暗黙のはずですか？これについては、phpdocのドキュメントはやや曖昧です。

dependencyがインターフェイスに基づいて噴射されると仮定します。インターフェイスは、メソッドが指定された例外をスローすることができることを文書化する必要があります。例外は、呼び出し元のコードで処理されなければならないか、その状況とは無関係である場合

それが重要ですか？

セマンティクスのすべての方法:)

Answer 1

あなたは、いくつかの場合に例外をスローすることができますパブリック関数（誰もがそれを使用することができます）作成している - ので、あなたは間違いなくあなたのdocblockで@throwsエントリを持っている必要があります。
あなたの依存関係から例外がスローされた場合 - これは内部実装であり、カプセル化されています - したがって、あなたの関数を使用する人はあなたの関数から何が期待できるのか分かりません。インタフェース・インジェクションの場合

- それは、クラスやインタフェースの行動の一部だ例外は、すべての可能な振る舞いを記述しなければならないため、インターフェイスは、すべての例外を記述しなければなりません。

try-catchブロックがあり、依存関係からすべての例外を処理する場合は、自分の例外をドキュメントブロックの@throwsエントリに含める必要があります。