Средства документирования во Flash MX

Как сделать Reference

Корневым элементом xml-документа, распознаваемого средой разработки Flash MX, является тег <customactions>. Он может содержать теги <actionspanel>, <colorsyntax>, <codehints> и <reference>.

<actionspanel> содержит описание дерева папок в панели Actions и оглавлении References. В <colorsyntax> перечисляются элементы кода, которые должны выделяться другим цветом в редакторе. <codehints> определяют контекстные подсказки. Теги <reference> содержат подробные описания элементов, перечисленных в <actionspanel>. Остановимся на каждом из этих тегов подробнее.

<actionspanel>.

Этот тег атрибутов не имеет, может содержать теги <folder> и <string>. Тег <folder> в свою очередь так же может содержать теги <folder> и <string>. Тег <string> вложенных тегов не имеет. Вся информация, которую несут теги <folder> или <string>, содержится в их атрибутах.

Тег <folder> отвечает за группу элементов (например, на рис. 12.2 это папка Lift, а так же содержащиеся в ней папки Methods и Properties ).

Многие атрибуты являются общими для тегов <folder> и <string>. Первый из них - name, его значение - это имя папки или элемента, отображаемое в панели Actions и оглавлении References. Атрибут id использует для гиперссылок в References (подробнее см. ниже). Чтобы не путаться, значения атрибутов id и name обычно делают одинаковыми. Атрибут tiptext содержит краткую информацию о папке или объекте, которая отображается в виде tooltip (всплывающей подсказки) в панели Actions или оглавлении References (рис. 12.3).

Рис. 12.3.

Кроме того, у тега <folder> есть булевский атрибут sort, по умолчанию true. Если sort установить равным false, то содержимое папки не будет сортироваться по алфавиту, а будет выведено именно в том порядке, в каком оно описано в xml-файле.

Атрибут version (число) указывает на номер версии плеера, начиная с которой можно использовать данный объект. Если в настройках публикации выставлена версия плеера ниже заданной атрибутом version, в панели Actions данная строчка будет подсвечена желтым, чтобы указатьn пользователю, что в данной версии плеера объект не работает. Если вы используете собственные классы, вам необходима версия плеера не ниже 6. Этот атрибут может быть как у тега <folder>, так и у тега <string>.

О специфических для тега <string> атрибутах text, type и object мы поговорим в следующих параграфах.

Текст References

Тексты References содержатся в тегах <reference>. Этот тег имеет атрибут path, в нем указывается путь в дереве папок, по которому должен быть доступен данный текст. Сам текст содержится внутри тега, в формате html. Из html-тегов поддерживаются <p>, <b>, <I>, <br> и <a>. В отличие от html, все теги обязательно должны быть закрыты. Для форматирования текста рекомендуется пользоваться предопределенными стилями (указываются в атрибуте class тега <p> ). Это стили titleStyle (заголовок, один на каждый объект), subTtle - подзаголовок и codeStyle - используется для примеров кода. В атрибуте href тега <a>, как и в html, указывается путь к документу, на который ведет ссылка, в следующем виде:" reference:[путь] ".

В примере 12.2 приведен xml-исходник описания одного из методов класса Lift. На рисунке 12.4 показано, как это описание выглядит в панели References.

<reference path="Lift/Methods/goto">
   <p class="titleStyle">Lift.goto</p>
   <p class="subTitle">Доступность</p>
   <p>Flash Player 6.</p>
   <p class="subTitle">Использование</p>
   <p class="codeStyle"><i>my_lift.</i>goto(<i>floor</i>)</p>
   <p class="subTitle">Параметры</p>
   <p><i>floor</i> - целое число. Номер этажа.</p>
   <p class="subTitle">Возвращает</p>
   <p> Номер этажа, на котором оказался лифт </p>
   <p class="subTitle">Описание</p>
   <p>Отправляет лифт на заданный этаж.</p>
   <p class="subTitle">См. также</p>
   <p class="codeStyle">
   <a href="reference:Lift">Класс Lift</a><br/>
   <a href="reference:Lift/Properties/minFloor">Lift.minFloor</a>
   <br/>
   <a href="reference:Lift/Properties/maxFloor">Lift.maxFloor</a>
   <br/>
   </p>
</reference>

Что именно писать в References - это, конечно, решает программист. Но лучше придерживаться стиля, в котором написаны References для встроенных объектов Flash MX. А именно, там должны содержаться следующие пункты:

1. Доступность - версия плеера, начиная с которой данный объект нормально работает.

   

   
   Рис. 12.4. Пример описания в References
2. Использование - синтаксис вызова, если речь идет о методе, создание объекта класса, и т. п. Если метод вызывается с аргументами, их лучше описать в отдельном подпункте.
3. Что возвращает метод. (Вероятно, вы заметили, что в документации от Macromedia в подпункте Returns в подавляющем большинстве случаев написано Nothing, в то время как в подпункте Description явно сказано о том, что метод что-то возвращает. Это скорее всего ошибка, которую повторять не стоит.)
4. Описание с примерами кода. Что должно быть в описании, лучше всего знает создатель описываемой программы. Но не следует забывать и о тех, кто эти описания будет читать. Чтобы все возможности ваших объектов были эффективно использованы, нужно описать их (и объекты, и возможности) как можно более подробно и понятно. При написании References стоит временно отбросить убеждение " copy / paste - это плохо". References - не программа, а человек - не интерпретатор, и он не будет читать все подряд. (К сожалению, если вы подумываете использовать XML entities как альтернативу copy / paste, вынуждены вас разочаровать: они не поддерживаются системой онлайн-документации Флэш МХ). Если у вас есть несколько почти идентичных методов (например getMinFloor и getMaxFloor ) и их описания практически совпадают, лучше все-таки давать максимально п олное описание каждому объекту - скорее всего, прочитано будет что-то одно, и вы никогда не угадаете, что именно. С другой стороны, если для понимания работы данного объекта нужна какая-то информация, напрямую к нему не относящаяся, чтобы не загромождать окно, лучше расположить ее там, где она более уместна, но в тексте описания обязательно дать на нее ссылку.
5. Ссылки на похожие объекты. Оптимальный вариант - 3-4 ссылки на объекты, которые действительно могут понадобиться читающим это описание. Например, в описании метода MovieClip.attachMovie содержатся ссылки на MovieClip.removeMovieClip, MovieClip.unloadMovie, Object.registerClass. Что вполне логично: если человек подгружает клип из библиотеки, то ему, может быть, захочется его тем или иным способом удалить. Да и вполне резонный вопрос: "А почему я клип подгрузил, а мои методы не работают?" еще не успевает возникнуть, как Object.registerClass тут как тут.