Есть у Java одна полезная утилита: JavaDoc. Она позволяет создавать документацию основываясь на комментариях в коде.
Зачем это нужно? Потому что всем нам лень писать документацию и поддерживать её по мере изменения кода. Используя JavaDoc можно просто писать хорошие и подробные комментарии в начале каждого метода и объявления класса. Запускаем утилиту и получаем удобную документацию.
Но JavaDoc это не только утилита, но ещё и стиль комментариев. Он удобен, понятен, однозначен и минималестичен. Есть и другие стили документирования, а некоторые из них могут использоваться и совместно с JavaDoc.
Вот пример заголовка функции Object.PointDistToLine(…) с комментариями в стиле JavaDoc;
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
/** * Calculates the distance of a given Point in world space to a given line, * defined by the vector couple (Origin, Direction). * * @param Point point to check distance to Axis * @param Line unit vector indicating the direction to check against * @param Origin point of reference used to calculate distance * @param OutClosestPoint optional point that represents the closest point projected onto Axis * * @return distance of Point from line defined by (Origin, Direction) */ native final function float PointDistToLine(vector Point, vector Line, vector Origin, optional out vector OutClosestPoint); |
А вот как будет выглядеть эта функция в документации. 
Про синтаксис и теги можно почитать например здесь.
Сейчас уже есть уйма инструментов для извлечения документации и в частности JavaDoc, но каждый из них привязан к какому-то конкретному языку (или нескольким языкам).
Unreal Script не является стандартным по синтаксису языком, хотя и схож с Java. Он имеет свои уникальные вроде state и defaultproperties, которые не воспримут обычные программы извлечения документации.
Я рассмотрю три решения, которые нашёл на просторах интернета и на своём компьютере.
UnCodeX
Лучшим инструментом для извлечения документации обычно является инструмент написанный под тот язык, из исходников которого собираются вытащить комментарии. И Unreal Script не является исключением.
Если вы работаете с Unreal Script, то уже наверняка знакомы с такой программой как UnCodeX. В UnCodeX есть своё средство для создания документации на основе исходного кода, лёгкое и при том очень эффективное.
Вызвать сборку документации по всем классам UScript можно в один клик, нажав кнопку “Create HTML files” (на рисунке она обозначена цифрой 1). После того как документация построится, её можно посмотреть, нажав на кнопку “Open output” (цифра 2). Так же, всё это можно проделать через меню “HTML Output”.
В настройках UnCodeX можно задать дополнительные параметры для построения документации, а так же настроить создание Help-файлов (формата *.chm).
Документация построенная UnCodeX вполне подойдёт для проекта любого размера. Однако у неё есть один небольшой минус — комментарии в стиле JavaDoc никак не обрабатываются, хотя часть базовых классов откомментирована в этом стиле.
ROBODoc
ROBODoc является универсальным инструментом для документирования исходного кода. Эту утилиту можно использовать с большинством известных (и даже пока не известных) языков.
Комментарии, обрабатываемые ROBODoc выглядят следующим образом
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
/****s* Directory/RB_Directory * NAME * RB_Directory -- the directory tree with the source files. * FUNCTION * Stores information about files in a directory tree. * The whole structure consist of two linked lists. One for * directory paths, and one for filenames. * EXAMPLE * The following show an example structure. * RB_Directory RB_Path * +-------+ +------+ +-------+ +-----------+ * | +-->| . |--->| ./sub |-->| ./sub/sub | * | | +------+ +-------+ +-----------+ * | | ^ ^ ^ * | | | | | * | | |-----------+ +------+ +------+ * | | | | | | * | | | | | | * | | +------+ +------+ +------+ +-------+ * | +-->| a.c |--->| b.c |-->| sa.c |-->| ssb.c | * +-------+ +------+ +------+ +------+ +-------+ * RB_Filename * * ATTRIBUTES * * first -- first RB_Filename in the list of files * * current -- the last file that was returned in * RB_Get_Next_Filename. * * last -- the last RB_Filename in the list of files * used for the insert operation * * first_path -- first RB_Path in the list of paths. * SOURCE */ struct RB_Directory { struct RB_Filename *first; /* TODO should be called files */ struct RB_Filename *last; struct RB_Path *first_path; /* TODO should be called paths */ }; /******/ |
После преобразования мы получим документацию следующего вида:
Как видно, о JavaDoc тут речи не идёт, (ROBODoc не поддерживает этот стиль комментариев). Так же мы видим, что комментарии нужно начинать и заканчивать рядом из звёздочек.
Проблема такого подхода в том, что достаточно сложно приучить команду программистов писать подобные комментарии.
Ещё, мне не удалось заставить его верно преобразовать кириллицу, но думаю что это возможно.
Вместе с ROBODoc можно скачать его исходные коды. Написан он на C. Судя по всему, проект ныне не поддерживается.
Natural Docs
В своих изысканиях, я так и не нашёл инструмента, который бы поддерживал синтаксис JavaDoc и работал с Uneral Script. В конце концов, я решил попробовать написать плагин к Natural Docs, который бы включил Unreal Script в список “нативно-поддерживаемых” языков этой программы.
Natural Docs тоже является универсальным инструментом для документирования кода. Этот инструмент может вытаскивать комментарии из многих языков, умеет преобразовывать текстовые файлы в HTML-документацию, и имеет возможность задавать свои правила для ещё не известных инструменту языков.
Для его работы на Windows придётся установить Active Perl (если он ещё не стоит).
Синтаксис JavaDoc по умолчанию поддерживается только для трёх языков: C#, Perl и Action Script (2 и 3).
Однако, Natural Docs идёт с исходными кодами (ещё бы, ведь написан он на интерпретируемом языке) и для него можно попытаться написать парсер для любого языка.
Собственно, на написание более-менее адекватного парсера у меня ушла неделя. К сожалению, пришлось внести много правок в сам движок (конструкции типа defautproperties не поддерживаются ядром). Так что пытаться подкинуть проделанную работу разработчикам, дабы они включили поддержку Unreal Script в новых версиях — пустая затея.
Пример документирования и документации можно посмотреть в начале статьи.
Выкладываю его тут, быть может кому пригодится.
Ссылка на скачивание: NaturalDocs_with_UScript_and_Ru.zip
В папке Sample лежит пример использования. Инструкция:
Помещаем исходники в src. Остальные каталоги не трогаем. После запуска run.bat в папке doc появится документация, а в папке project — файлы проекта (контрольные суммы файлов, настройки языков проекта и настройки меню документации).
Для того чтобы документация выводилась на английском, убираем “-l ru” в UpdateDocs.pl.
Если нужно внести свои языки перевода, смотрим пример в “\Modules\NaturalDocs\Translations”.
По мере исправлений и улучшений, буду обновлять этот пост и выкладывать новые версии.
Для гиков
С помощью ROBODoc и NaturalDocs можно автоматизировать создание документации. Например, обновлять документацию на веб сервере при коммите в master (trunk) системы контроля версий.
Leave a Reply
You must be logged in to post a comment.