UScript & JavaDoc

Есть у Java одна полезная утилита: JavaDoc. Она позволяет создавать документацию основываясь на комментариях в коде.

Зачем это нужно? Потому что всем нам лень писать документацию и поддерживать её по мере изменения кода. Используя JavaDoc можно просто писать хорошие и подробные комментарии в начале каждого метода и объявления класса. Запускаем утилиту и получаем удобную документацию.

Но JavaDoc это не только утилита, но ещё и стиль комментариев. Он удобен, понятен, однозначен и минималестичен. Есть и другие стили документирования, а некоторые из них могут использоваться и совместно с JavaDoc.

Вот пример заголовка функции Object.PointDistToLine(…) с комментариями в стиле JavaDoc;

А вот как будет выглядеть эта функция в документации. NaturalDocs_Sample

Про синтаксис и теги можно почитать например здесь.

 

Сейчас уже есть уйма инструментов для извлечения документации и в частности JavaDoc, но каждый из них привязан к какому-то конкретному языку (или нескольким языкам).

Unreal Script не является стандартным по синтаксису языком, хотя и схож с Java. Он имеет свои уникальные вроде state и defaultproperties, которые не воспримут обычные программы извлечения документации.

Я рассмотрю три решения, которые нашёл на просторах интернета и на своём компьютере.

UnCodeX

Лучшим инструментом для извлечения документации обычно является инструмент написанный под тот язык, из исходников которого собираются вытащить комментарии. И Unreal Script не является исключением.

Если вы работаете с Unreal Script, то уже наверняка знакомы с такой программой как UnCodeX. В UnCodeX есть своё средство для создания документации на основе исходного кода, лёгкое и при том очень эффективное.

Вызвать сборку документации по всем классам UScript можно в один клик, нажав кнопку «Create HTML files» (на рисунке она обозначена цифрой 1). После того как документация построится, её можно посмотреть, нажав на кнопку «Open output» (цифра 2). Так же, всё это можно проделать через меню «HTML Output».

 

HTMLUnCodeX

В настройках UnCodeX можно задать дополнительные параметры для построения документации, а так же настроить создание Help-файлов (формата *.chm).

Документация построенная UnCodeX вполне подойдёт для проекта любого размера. Однако у неё есть один небольшой минус — комментарии в стиле JavaDoc никак не обрабатываются, хотя часть базовых классов откомментирована в этом стиле.

ROBODoc

ROBODoc является универсальным инструментом для документирования исходного кода. Эту утилиту можно использовать с большинством известных (и даже пока не известных) языков.

Комментарии, обрабатываемые ROBODoc выглядят следующим образом

После преобразования мы получим документацию следующего вида:

ROBODoc sampleКак видно, о 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) системы контроля версий.

Поделиться

Оставить ответ