Question

How should I comment an event handler param?
I mean, should I comment event handler param?

Example:

TimerMessage class extends Timer.

TimerMessage class, has a setMessage method, which stores a text message whithin its public
var ‘message’.

in usage:

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)
}

How should I comment displayMessage handler?

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

Like that?

I think that @param part, is too redundant.

What you think?

Thanks

Answer 1

No it’s not too redundant. I usually press Command-Shift-D (on Mac, on windows I think you replace Command key with the Control key) before any method or variable that I would like to document.

Flash Builder generates a comment template for you to fill in, including a @param for each argument in the method.

This can be turned into beautiful looking HTML documentation for your code with the asdoc command. At which point all those redundant @param things seem less redundant, and actually pretty neat. There are other tags too.