Вся правда о ASDoc комментариях. Часть первая. Создание ASDoc комментариев. //Выбраны основные положения

Оригинал. 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]