Оригинал.
LIFE.Flash.
А вместе с ASDoc пришел новый набор правил, с которыми я хотел бы вас познакомить. Правил довольно много. Формат ASDoc это, модифицированный под ActionScript, формат javadocs.
Элементы, поддерживаемые в ASDoc ASDoc поддерживает следующие элементы, встречающиеся в ActionScript файле:
- многострочные комментарии (multi-line comments)
- ASDoc теги
- определения class и interface
- свойства
- методы
- set/get методы
- теги метаданных (metadata tags)
Включение ASDoc комментариев
Документация в исходном коде, включается в комментарии, которые начинаются с /** (две звездочки) и заканчиваются */ .Если вы используйте многострочный текст, для документирования того или иного элемента кода, разделяйте каждую новую строчку промежуточной (или как ее еще называю – ведущей) звездочкой. Применение данного метода делает ваш код более читабельным и, что не менее важно, гарантирует правильный синтаксический анализ ваших комментариев.
Когда ASDoc выполняет грамматический разбор комментариев, ведущие звездочки (*) после начала комментария /**, табуляция и пробелы (если они есть) после ведущих звездочек, удаляются. Остается лишь текст.
Пример ASDoc комментария:
/**
* Comment text.
*
* @tag Tag text.
*/
Для того, что бы добавить дополнительный параграф используйте стандартный HTML-тег <p></p>.
Вставлять комментарий необходимо до объявления класса, интерфейса, конструктора или тега метаданных.
ASDoc игнорирует комментарии, вставленные в тело функции. Признается только один комментарий, который описывает функцию до ее объявления.
Также, распространенной ошибкой, является вставка комментария описывающий класс, не над непосредственным объявлением класса, а над import. Избегайте данной ошибки, так как ASDoc просто проигнорирует такой комментарий.
Основное описание начинается сразу после разделителя /** и продолжается до раздела тегов. Первое предложение основного описания, должно содержать краткое, но полное описание сущности комментируемого (класса, функции, метода, свойства и т.д.). Основное описание заканчивается сразу после первой точки или разделителя строки (\r).
Секция тегов, начинается сразу после первого тега, который объявляется символом @ в начале линии. С помощью тегов создаются отдельные заголовки, например такие как –
- param (параметры),
- return (результаты возврата функции), а также
- see (смотреть, т.е. своеобразная ссылка, на другую функцию, документацию которой необходимо прочитать).
Вы можете создавать неограниченное число тегов; некоторые теги могут повторяться, например, такие как @param и @see, но (!) другие нет.
ASDoc генерирует документацию всех публичных элементов ActionScript-класса, даже если вы игнорируете комментарии. Если вы хотите что бы ASDoc игнорировал какой-то элемент, вы можете использовать тег @private. Тег @private может содержать дополнительный пояснительный текст.
Тегом @private, вы можете запретить генерацию не только приватных элементов класса, но и всего класса в частности (так как документация генерируется и для всех публичных классов тоже). Для этого необходимо включить тег @private в описание класса.
Несколько правил парсинга (синтаксического анализа) ASDoc комментариев:
- Все элементы кода, находящиеся после ASDoc комментария, копируются в генерируемый файл документации.
- Если у ASDoc комментарий отсутствует, то в элемент кода генерируется без всякой документации.
- Если в ASDoc комментарии встречается тег @private, ASDoc игнорирует это элемент кода (если эта функция не изменена в конфигурации ASDoc).
В ASDoc однострочный комментарий // и многострочный комментарий, начинающийся с одной звездочкой /*, игнорируются. - Форматированные участки (<p>, <b>, <i> и т.п.) встречающиеся в ASDoc комментариях допускаются. Но учтите, некоторые элементы должны вводиться в виде кодовых эквивалентах HTML. Например, знак больше (>) или меньше (<) должны быть прописаны как < и >. Или например амперсанд “&” должен быть прописан как &.
- Не забывайте, что теги HTML обязаны наследовать правила форматирования формата XML, т.е. если вы открываете тег, то он должен быть обязательно закрыт. Например тег <li> должен быть закрыт тегом </li>.
ActionScript разработчики знают о том, что свойства, схожие по типу данных, можно объявлять через запятую. Но, при генерации документации, такая особенность не учтена, что в принципе вполне логично. Каждое свойство должно объявляться индивидуально.
Геттер/сеттер методы обрабатываются ASDoc отдельно, так как эти элементы используются как свойства, хотя на самом деле ими не являются. Поэтому ASDoc создает для каждого геттер/сеттер метода документацию, аналогичную документации свойств.
Обычно для геттер/сеттер метода создается единый комментарий, с одним описанием. А сеттер комментируется тегом @private. Это рекомендуется делать, так как обычно геттер объявляется раньше сеттера.
ASDoc может выдать ошибку, если ваш исходный файл содержит символы, имеющие кодировку не UTF-8. В этом случае, при генерации документации, ASDoc вернет номер строки, где встречаются некорректные символы.
Обработка метаданных
Для определения элементов компонента, Flex использует теги метаданных. ASDoc поддерживает теги метаданных и обращается к ним также, как к методам и свойствам.Поддерживаемые теги метаданных в ASDoc:
- [Event(name=" eventName ", type=" eventType ")]
- [Style(name=" styleName ", type=" type ", format=" format ", inherit="yesno")]
- [Effect(name=" effectName ", event=" triggeringEventName ")]
- [Bindable("event="eventname")]
- [DefaultProperty(" name ")]
- [Exclude(name=" elementName ", kind="propertymethodeventstyleeffect")]
Разработчики применяют теги метаданных, чтобы документировать события, стили, эффекты, применяемые в классе. Метаданные, бывают в виде [Event args], [Style args], и [Effect args] и обычно создаются сразу после объявления класса.
/** * Defines the name style. */
[Style "name"]
Для событий и эффектов, тег метаданных включает в себя имя класса, непосредственно связанного с событием или эффектом. Приведем пример из класса mx.controls.Button:
/**
* ... this event is dispatched repeatedly as long as the button stays down.
*
* @eventType mx.events.FlexEvent.BUTTON_DOWN
*/
[Event(name="buttonDown", <strong>type="mx.events.FlexEvent"</strong>)]
Для такого комментария, ASDoc сделает следующее:
- В конечном файле, класса mx.controls.Button, ASDoc создаст ссылку на класс события (mx.events.FlexEvent), определенного в аргументе type.
- Также, ASDoc копирует описание константы, значение которой возвращает Event.type класса Button. В ASDoc вы можете использовать тег @eventType, для определения константы. В данном примере, ASDoc копирует описание константы mx.events.FlexEvent.BUTTON_DOWN класса Button. Константа mx.events.FlexEvent.BUTTON_DOWN определяет значение объекта, связанного с событием.
В ASDoc комментарии, для константы mx.events.FlexEvent.BUTTON_DOWN вы должны вставить в таблицу возвращаемые значения (bubbles, cancelable, target, и currentTarget) свойства класса Event.
Для примера, рекомендуется посмотреть весь класс mx.controls.Button и классы mx.events.FlexEvent.
Для каждого метода или свойства, вы должны определять, какие события отправляются (или как говорят “диспатчатся”) методу или свойству. Для этого необходимо использовать тег @event описывая каждый метод или свойство. Тег @event имеет следующий формат:
@event eventName eventObjectClassName [description]
