Exceptions -- Dokumentation

[zehbaeh]

Hallo,

ich wollte mal wissen wie ihr die Dokumentation von "indirekten" Exceptions in Methoden handhabt.
Beispiel:

  
class FooBar  
{  
    public function __construct()  
    {  
        $this->foo();  
    }  
  
    public function baz()  
    {  
        $this->bar();  
    }  
  
    /**  
     * @throws Exception BAR anyway  
     */  
    public function bar()  
    {  
        throw new Exception(Exception::BAR);  
    }  
  
    /**  
     * @throws Exception FOO anyway  
     */  
    protected function foo()  
    {  
        throw new Exception(Exception::FOO);  
    }  
}  

Dokumentiert ihr das mögliche "indirekte" werfen einer Exception im Konstruktor bzw. in der Methode baz()?

Ich mache das i.d.R mit einer @internal Anmerkung, so richtig überzeugend finde ich das allerdings nicht.
Beispiel:

  
/**  
 * @internal Exceptions thrown by internally used {@see self::bar} are passed  
 */  
public function baz()  
{  
    $this->bar();  
}  

[jobo]

Hallo,

http://framework.zend.com/wiki/display/ZFDEV2/Coding+Standards#CodingStandards-InlineDocumentation fand ich immer ganz nützlich. Aber hilft hier vielleicht nicht direkt, oder?

Gruß

jobo

[zehbaeh]

http://framework.zend.com/wiki/display/ZFDEV2/Coding+Standards#CodingStandards-InlineDocumentation fand ich immer ganz nützlich. Aber hilft hier vielleicht nicht direkt, oder?

Nein das hilft nicht wirklich weiter.
So wie dort beschrieben mache ich es ja bereits bei Methoden die direkt (also selbst) eine Exception werfen.
Mir geht es um Methoden die andere Methoden aufrufen die Exceptions werfen und um den Umstand ob und wie in der aufrufenden Methode darauf hingewiesen werden soll.

[Tom]

Hello,

http://framework.zend.com/wiki/display/ZFDEV2/Coding+Standards#CodingStandards-InlineDocumentation fand ich immer ganz nützlich. Aber hilft hier vielleicht nicht direkt, oder?

Nein das hilft nicht wirklich weiter.
So wie dort beschrieben mache ich es ja bereits bei Methoden die direkt (also selbst) eine Exception werfen.
Mir geht es um Methoden die andere Methoden aufrufen die Exceptions werfen und um den Umstand ob und wie in der aufrufenden Methode darauf hingewiesen werden soll.

Also ich würde nur dokumentieren:

• Exceptions, die von der Methode selbst ausgelöst werden
• Exceptions, die von der Methode gefangen werden und was dann warum _hier_ zu geschehen hat
• Exceptions, die von der Methode keinesfalls gefangen werden dürfen, und !warum! nicht.

Alles Andere ist bei Verwendung des das Exception-Model sowieso einheitlich zu regeln, sonst kann man auch gleich wieder auf diskrete Fehlerwerte von Funktionen zurückfallen.

Exceptions sind solange in Richtung Programmwurzel durchzureichen, bis sie behandelt werden können. Und die Ausnahmen der Ausnahmen-Behandlung sollte man daher dokumentieren.

Da lob ich mir meine Runtime-Errors :-P

Liebe Grüße aus dem schönen Oberharz

Tom vom Berg