четверг, января 17, 2008

Теги ASDoc. AS3

Теги ASDoc

@copy reference - копирует ASDoc комментарий из reference. Копируется основное описание и теги @param и @return. Остальные теги не копируются.
Пример: @copy #stop, @copy MovieClip#stop

@default value - указывает значение по умолчанию value для свойства, стиля или эффекта.
Пример: @default 0xCCCCCC

@eventType package.class.CONSTANT - комментарий для тега метаданных [Event]. Описывает константу, которая определяет значение свойства Event.type объекта event, ассоциированного с событием.

@eventType String - комментарий для констатны события. Указывается перед определением константы события и определяет название события. Если тег не указывается, комментарий констатны не заносится в описываемый класс.

@example exampleText - вставляет пример в текущее описание, при этом применяет к тексту кода особый стиль и генерирует заголовок. Сам код заключается в теги <listing version="3.0"></listing>. Код будет расположен в серой прямоугольной прокручиваемой области с сохранением пробельных символов.
Пример: @example The following code sets the volume level for your sound: <listing version="3.0"> var mySound:Sound = new Sound(); mySound.setVolume(VOL_HIGH); </listing>

@exampleText string - используется во внешних файлах с примерами, на которые осуществляется ссылка из тега @example. Этот комментарий должен располагаться в начале, перед первой строкой или в конце - ниже последней строки примера. Во внешних файлах примеров допустимо указывать только один комментарий в начале и один в конце.
Пример: /** * This text does not appear * in the output. * @exampleText But this does. */

@inheritDoc - используется для комментирования перекрываемых свойств и методов класса-потомка. При этом, в описание класса-потомока копируется комментарий из класса-предка, или из интерфейса, который реализуется этим классом-потомком. Копируется только содержимое тегов @param и @return. Остальные теги игнорируются. При формировании комментария для этого тега, соблюдается следующий порядок:
1. Интерфейсы, используемые описываемым классом (в свободном порядке) и все их базовые интерфейсы.
2. Прямой предок класса.
3. Интерфейсы, используемые классом прямого предка и все их базовые интерфейсы.
4. Повторяются п. 2 и 3 до тех пор, пока не будет достигнут класс Object.
Пример: @inheritDoc

@internal text - внутренний комментарий, который не будет включен в документацию.
Пример: @internal Please do not publicize the undocumented use of the third parameter in this method.

@param paramName description - добавляет комментарий, описывающий метод с именем paramName.
Пример: @param fileName The name of the file to load.

@private - исключает внесение комментируемого элемента в документацию.
Пример: @private

@return description - добавляет в описание метода раздел Return - комментарий касательно возвращаемого значения. Возвращаемый тип определяется ASDoc автоматически.
Пример: @return The translated message.

@see reference [displayText] - добавляет в описание метода раздел See Also - ссылка на описание элемента класса.
Пимер: @see flash.display.MovieClip

@throws package.class.className description - документирует ошибку (исключение), которую может генерировать метод.
Пример: @throws SecurityError Local untrusted SWFs may not communicate with the Internet.


Не ASDoc теги

Я не нашел эти теги в Adobe LiveDocs, но люди их пользуют.

@author - автор кода. Пример @author Name
@version - версия кода. Пример @version 3.15
@langversion - языковая версия. Пример @langversion ActionScript 3.0
@playerversion - версия Flash Player. Пример @playerversion Flash 8


Примеры использования тега @see:

@see "Just a label" - текстовая строка
@see http://www.cnn.com - ссылка на внешний веб-сайт
@see package-detail.html - ссылка на локальный HTML-документ
@see Array - класс верхнего уровня
@see AccessibilityProperties - пакет
@see flash.display.TextField - класс TextField в пакете flash.display
@see Array#length - свойство класса верхнего уровня Array
@see flash.ui.ContextMenu#customItems - свойство класса ContextMenu из пакета flash.ui
@see #updateProperties() - метод в описываемом классе
@see Array#pop() - метод класса верхнего уровня Array
@see flash.ui.ContextMenu#clone() - метод класса ContextMenu из пакета flash.ui
@see global#Boolean() - метод пакета верхнего уровня global
@see flash.util.#clearInterval() - метод из пакета flash.util

Относительно правил ASDoc-комментирования смотреть списанное из чужой тетради.

PS: Наконец решил расставить все точки над Ы и правильно комментировать свой код.

* * *

Другие замеченные теги

@mxml
@includeExample
@event

2 комментария:

a_[w] комментирует...

Спасибо!
Это описание очень пригодилось!

Jloa комментирует...

Новая версия ASDocUI
Версия: 1.2 [win32/mac*]

Изменения:
====================================
- теперь указываем папку с классом/пакетом/кучей пакетов (а не как раньше - по одному классу)
- пофиксил execute команду
- лог теперь для удобства (если стоит галка сохр) сохр в папку док-ов
====================================
====================================
Теперь это упрощенный вариант Apache Ant с win интерфейсом.
Тестировал на Flex Builder 2.0.1, 3.0.
====================================
* - скоро появится версия под Мак. Пишите мне на julious.loa@gmail.com я вас добавлю в список рассылки и вышлю вам как только так сразу.

Скачать: http://www.lp-design.ru/forum/files/ASDocUI_1.2.rar