Комментировать параметры обработчиков событий

Question

Как я могу прокомментировать параметр обработчика события? Я имею в виду, должен ли я комментировать обработчик события param?

Пример:

TimerMessage класс расширяет таймер.

Класс TimerMessage имеет метод setMessage, в котором хранится текстовое сообщение в его общедоступном var 'message'.

в использовании:

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

Как я должен комментировать обработчик displayMessage?

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

Нравится?

Я думаю, что часть @param слишком избыточна.

Что вы думаете?

Thanks

Answer 1

Нет, это не слишком избыточно. Обычно я нажимаю Command-Shift-D (на Mac, в окнах, я думаю, вы заменяете клавишу Command клавишей Control) перед любым методом или переменной, которую я хотел бы документировать.

Flash Builder создает шаблон комментария для заполнения, включая @param для каждого аргумента метода.

Это может быть превращено в красивую документацию HTML для вашего кода с помощью asdoc command. В этот момент все эти избыточные вещи @param кажутся менее избыточными и на самом деле довольно опрятными. There are other tags too.