Event-Handler-Parameter eingeben

Question

Wie soll ich einen Event-Handler-Parameter kommentieren? Ich meine, sollte ich Event-Handler-Parameter kommentieren?

Beispiel:

TimerMessage Klasse erweitert Timer.

TimerMessage-Klasse, verfügt über eine setMessage-Methode, die eine Textnachricht in ihrer öffentlichen var 'Nachricht' speichert.

in Nutzung:

var timer_message:TimerMessage = new TimerMessage(1000, 1) 
timer_message.setMessage('hello') 
timer_message.addEventListener(TimerEvent.TIMER_COMPLETE, displayMessage) 

private function displayMessage(e:TimerEvent):void{ 
txt.text = e.target.message 
e.target.stop() 
e.target.removeEventListener(TimerEvent.TIMER_COMPLETE, displayMessage) 
} 

Wie soll ich einen Kommentar displaymessage Handler?

/* Displays message on main stage 
* @param e - timer event 
* */ 

So?

Ich denke, dass @ Param Teil ist zu redundant.

Was denken Sie?

Danke

Answer 1

Nein, es ist nicht zu redundant. Gewöhnlich drücke ich Command-Shift-D (auf Mac, auf Windows denke ich, dass Sie die Befehlstaste durch die Strg-Taste ersetzen) vor jeder Methode oder Variable, die ich dokumentieren möchte.

Flash Builder generiert eine Kommentarvorlage, die Sie ausfüllen müssen, einschließlich eines @ param für jedes Argument in der Methode.

Dies kann in schön aussehende HTML-Dokumentation für Ihren Code mit der asdoc command umgewandelt werden. An diesem Punkt scheinen all diese redundanten @ param-Dinge weniger redundant und eigentlich ziemlich ordentlich. There are other tags too.