Документирование событий в ActionScript3 @eventType
При написании кода очень важно оставлять комментарии и документировать методы/классы/события и т.д. Правильно описанный и задокументированный класс проще поддерживать, среда сможет дать более полную информацию о нем (в данном случае например предложить правильное автозаполнение для addEventListener/removeEventListener), да и выглядит он просто красивее.
Итак рассмотрим, как следует поступать, когда ваш as3 класс диспатчит события. Пусть у нас есть класс MyDispatcher, который должен испускать события при начале и окончании работы. Опишем его и задокументируем в соответствии с правилами ASDoc.
Событие
Для испускаемых событий желательно реализовать отдельный класс. В этом классе мы будем описывать константы типов испускаемых событий. Также Вы можете добавлять свойства или методы в класс события, по необходимости.
Создаем класс MyEvent, наследник Event. При наследовании события, не забывайте корректно переопределять метод Event.clone().
Далее перечислим все типы событий в статических константах класса, а в комментарии к константе необходимо еще раз указать тип события с помощью тега @eventType:
/** * Определяет значение свойства <code>type</code> события <code>start</code> * @eventType start */ public static const START:String = “start”;
В самом комментарии, помимо стандартного текста о том, что константа определяет тип события, также принято описывать специфичное поведение или набор свойств события с таким типом.
При задании типа события нужно использовать двойные кавычки.
Диспатчер
Далее переходим к классу, испускающему событие. Все события, которые может испускать класс, необходимо описывать с помощью метатега [Event] до объявления класса (или интерфейса).
[Event(name="start", type="ru.greymag.events.MyEvent")]
name - это тип события, type - класс события (включая пакет). В комментарии к метатегу нужно указать соответствующую константу опять же с помощью тега @eventType:
/** * Событие рассылается при начале работы * @eventType ru.greymag.events.MyEvent.START */ [Event(name="start", type="ru.greymag.events.MyEvent")]
В самом комментарии следует описать ситуацию, когда будет диспатчится событие.
Note
Что касается текста комментариев - здесь приведены рекомендации от Adobe (таким правилом описания руководствуется среда разработки от Adobe при подсказке вариантов автозаполнения, а также утилита для генерации документации). Однако при использовании других инструментов Вы можете увидеть не то, что ожидаете. Например IntelliJ IDEA при автозаполнении будет показывать комментарий именно к константе события, а не к метатегу.
Вот и все.
Код
Полный код для примера:
package ru.greymag.events
{
import flash.events.Event;
public class MyEvent extends Event
{
/**
* Определяет значение свойства <code>type</code> события <code>complete</code>
* @eventType complete
*/
public static const COMPLETE :String = “complete”;
/**
* Определяет значение свойства <code>type</code> события <code>start</code>
* @eventType start
*/
public static const START :String = “start”;
public function MyEvent(type:String, bubbles:Boolean = false, cancelable:Boolean = false)
{
super(type, bubbles, cancelable);
}
override public function clone():Event
{
return new MyEvent(type, bubbles, cancelable);
}
}
}
package ru.greymag.example
{
import flash.events.EventDispatcher;
import ru.greymag.events.MyEvent;
/**
* Событие рассылается при начале работы
* @eventType ru.greymag.events.MyEvent.START
*/
[Event(name="start", type="ru.greymag.events.MyEvent")]
/**
* Событие рассылается при завершении работы
* @eventType ru.greymag.events.MyEvent.COMPLETE
*/
[Event(name="complete", type="ru.greymag.events.MyEvent")]
public class MyDispatcher extends EventDispatcher
{
function MyDispatcher()
{
super();
}
public function start():void
{
this.dispatchEvent(new MyEvent(MyEvent.START));
}
public function stop():void
{
this.dispatchEvent(new MyEvent(MyEvent.COMPLETE));
}
}
}