Я все время думал, что создание документации к коду – довольно сложное занятие, но только сегодня узнал, как я ошибался. А все благодаря возможностям FlashDevelop (здесь я рассматриваю версию 3.3.4).
Всем известно, что в комплекте с FlexSDK (который необходим для разработки Flash-приложений без использования Flash IDE) поставляется инструмент ASDoc – программа, работающая из командной строки и позволяющая из особым образом отформатированных комментариев к коду генерировать документацию. Но работать с программами из командной строки неудобно, и тут на помощь приходит FlashDevelop.
Чтобы создать документацию в html-формате нужно сначала написать комментарии к коду. Рассмотрим основные правила и приемы для написания таких комментариев.
Для того, чтобы создать заготовку для документации к какому-либо методу, свойству или описания всего класса, нужно всего лишь перед комментируемым участком кода набрать: /**, и тогда появиться следующая подсказка:
Выбрав пункт Empty, мы получим пустую заготовку:
Во второй строчке этого комментария можно ввести описание следующего за ним public-свойства, getter’а / setter’а, или всего класса.
Выбрав пункт Method details, мы получим заготовку для подробной документации метода:
На второй строке получившегося комментария можно написать описание метода.
На строке с тегом @param имяПараметра пишется описание данного параметра
Строка с тегом @return описывает возвращаемый методом результат.
Все строки заполнять необязательно, некоторые можно и удалить.
Это были основные теги, со списком остальных Вы можете ознакомиться например здесь (Теги ASDoc. AS3).
Кроме автоматического варианта создания заготовки комментария-документации к методу, Вы можете также сами прописывать тэги. Для этого, находясь в комментарии, Вам достаточно набрать @, и тогда появиться список всех тэгов:
Задокументировав таким образом наш класс, мы может перейти непосредственно к созданию справки в html-формате. Для этого в меню Tools нужно выбрать пункт Documentation Generator…:
В появившемся диалоговом окне заполняем следующие поля:
Page title – заголовок страницы документации
Exclude classes – здесь перечисляем через запятую классы, документацию к которым создавать не нужно
Output directory – папка, в которую будет помещена справка (адрес этой папки не должен содержать кириллических символов)
Classpaths – список папок с as-файлами
В выпадающем списке выбираем пункт ASDOC (AS3).
После всего этого мы можем жать на кнопку Generate. Вам придется подождать некоторое время, пока будет создаваться документация. После завершения операции должна открыться вкладка Output с сообщением о результате операции (если в коде были ошибки, то в данной вкладке они будут отмечены).
Чтобы каждый раз для данного проекта не прописывать все настройки по созданию документации, Вы можете воспользоваться кнопками Save Project… и Open Project… (названия, думаю, говорят сами за себя).
На этом на сегодня все.
Всем известно, что в комплекте с FlexSDK (который необходим для разработки Flash-приложений без использования Flash IDE) поставляется инструмент ASDoc – программа, работающая из командной строки и позволяющая из особым образом отформатированных комментариев к коду генерировать документацию. Но работать с программами из командной строки неудобно, и тут на помощь приходит FlashDevelop.
Чтобы создать документацию в html-формате нужно сначала написать комментарии к коду. Рассмотрим основные правила и приемы для написания таких комментариев.
Для того, чтобы создать заготовку для документации к какому-либо методу, свойству или описания всего класса, нужно всего лишь перед комментируемым участком кода набрать: /**, и тогда появиться следующая подсказка:
Во второй строчке этого комментария можно ввести описание следующего за ним public-свойства, getter’а / setter’а, или всего класса.
Выбрав пункт Method details, мы получим заготовку для подробной документации метода:
На строке с тегом @param имяПараметра пишется описание данного параметра
Строка с тегом @return описывает возвращаемый методом результат.
Все строки заполнять необязательно, некоторые можно и удалить.
Кроме автоматического варианта создания заготовки комментария-документации к методу, Вы можете также сами прописывать тэги. Для этого, находясь в комментарии, Вам достаточно набрать @, и тогда появиться список всех тэгов:
Exclude classes – здесь перечисляем через запятую классы, документацию к которым создавать не нужно
Output directory – папка, в которую будет помещена справка (адрес этой папки не должен содержать кириллических символов)
Classpaths – список папок с as-файлами
В выпадающем списке выбираем пункт ASDOC (AS3).
После всего этого мы можем жать на кнопку Generate. Вам придется подождать некоторое время, пока будет создаваться документация. После завершения операции должна открыться вкладка Output с сообщением о результате операции (если в коде были ошибки, то в данной вкладке они будут отмечены).
Чтобы каждый раз для данного проекта не прописывать все настройки по созданию документации, Вы можете воспользоваться кнопками Save Project… и Open Project… (названия, думаю, говорят сами за себя).
На этом на сегодня все.
Никогда ранее не задавался вопросом создания документации для собственного кода, и тем не менее прочел с интересом. Спасибо за качественный блог. Всегда приятно находить такие! :) Буду новым постоянным читателем.
ОтветитьУдалить@jafored буду стараться :)
ОтветитьУдалить