jdgen $Revision:1.0.1$
$Date:Sun Mar 03 17:03:04 2002$
Для языка Java был предложен довольно интересный способ создания программной документации - т.н. комментарии javadoc. На первый взгляд удобно - пишешь программу и сразу же документацию к ней. Но, это в теории. В своей практике я столкнулся с несколькими трудностями в применении javadoc-комментариев:
На практике получается, что когда программа разрабатывается, javadoc комментарии практически не создаются. Но приходит время передавать исходные тексты заказчику и для программистов наступают тяжелые времена - нужно просматривать массу исходных файлов, создавать javadoc там, где их нет и проверять там, где они есть. Именно для облегчения этого рутинного процесса и предназначена утилита jdgen.
Утилита jdgen просматривает Java-файл и:
По-умолчанию, jdgen переписывает исходный java-файл (если у него не установлен аттрибут read-only). Но можно указать jdgen только проверить файл, не изменяя его.
Путь изначально у нас был следующий java-файл:
package org.eao197.fpg; public interface fpg_syntax_proc_t { public Object run( fpg_parser_t parser, int fpg_stack_pos ); };
Запускается утилита jdgen:
jdgen -f fpg_syntax_proc_t.java
и файл приобретает вид:
package org.eao197.fpg; /** * FIX ME: missing javadoc. */ public interface fpg_syntax_proc_t { /** * FIX ME: missing javadoc. * @param parser FIX ME: param. * @param fpg_stack_pos FIX ME: param. * @return FIX ME: return. */ public Object run( fpg_parser_t parser, int fpg_stack_pos ); };
Если теперь запустить jdgen в режиме проверки и поиска фразы "FIX ME", то мы получим:
$jdgen -checkonly -checkfixme -f fpg_syntax_proc_t.java fpg_syntax_proc_t.java: process interface fpg_syntax_proc_t... fpg_syntax_proc_t: there is 1 occurence of FIX ME in javadoc run: there are 4 occurences of FIX ME in javadoc
Если модифицировать файл, например, так (заполняем комментарии, удаляем возвращаемое значение, переименовываем параметр parser, добавляем параметр result, добавляем секцию throws, но не изменяем комментария):
package org.eao197.fpg; /** * Base class for syntax procedures */ public interface fpg_syntax_proc_t { /** * Procedure start point * @param parser the parser object * @param fpg_stack_pos position in syntax * symbols stack * @return result syntax symbol data */ public void run( fpg_parser_t parser_object, int fpg_stack_pos, Object[] result ) throws Exception; };
То, после работы jdgen будет получено:
$jdgen -f fpg_syntax_proc_t.java fpg_syntax_proc_t.java: process interface fpg_syntax_proc_t... run: parser_object: parameter not defined in javadoc result: parameter not defined in javadoc parser: parameter defined in javadoc but not exists in Java Exception: throws not defined in javadoc javadoc defined return value for void-method
package org.eao197.fpg; /** * Base class for syntax procedures. */ public interface fpg_syntax_proc_t { /** * Procedure start point. * @param parser_object FIX ME: param. * @param fpg_stack_pos position in syntax * symbols stack. * @param result FIX ME: param. * @throws Exception FIX ME: throws. */ public void run( fpg_parser_t parser_object, int fpg_stack_pos, Object[] result ) throws Exception; };
Утилита jdgen распространняется в виде уже скомпилированного исполнимого файла для платформы Win32 (архив jdgen.win32.rar) и в виде исходных текстов (архив jdgen.rar).
В случае уже скомпилированной версии jdgen необходимо разархивировать jdgen.win32.rar в подходящий каталог. Если вы хотите вызывать jdgen не указывая явно путь к jdgen, то необходимо либо прописать каталог с jdgen.exe в переменную среды PATH, либо скопировать jdgen.exe в один из каталогов, прописанных в PATH.
В случае с исходными тестами необходимо разархивировать jdgen.rar в подходящий каталог и скомпилировать утилиту jdgen. После получения скомпилированного варианта jdgen можно либо прописать каталог с jdgen в переменную среды PATH, либо скопировать скомпилированный вариант jdgen в один из каталогов, прописанных в PATH.
Утилита jdgen написана с применением STL. Поэтому для компиляции необходимо, чтобы компилятору была доступна библиотека STL.
Так же сложности при компиляции может вызвать подключение стандартного заголовочного файла strstream.h. На платформах, вышедших из MS-DOS (Win32 и OS/2), этот файл имеет имя strstrea.h. На платформе Linux в составе компилятора GCC этот файл имеет нормальное название strstream.h. Для преодоления подобных различий в каталоге с jdgen неходится заглушка strstream.h, который в зависимости от платформы загружает либо стандатный файл strstream.h, либо стандартный файл strstrea.h. Если при компиляции возникнут какие-либо проблемы с подключением данных стандартных заголовочных файлов, то необходимо внести соответствующие изменения в заглушку strstream.h. (Если вы столкнулись с подобными проблемами и преодолели их, то сообщите, пожалуйста, об этом мне [eao197@yahoo.com], что бы я смог включить ваши изменения в код jdgen).
Утилита jdgen разрабатывалась с использованием
mxx v.4. Поэтому наиболее
простым способом компиляции jdgen является применение mxxc:
mxxc -f jdgen.4xx -d RELEASE
Для компилятора Visual C++:
cl -Fejdgen.exe -O2 -GX -DNDEBUG *.cpp
Для компилятора Borland C++:
bcc32 -ejdgen.exe -O2 -DNDEBUG -w-par -w-aus *.cpp
Для компилятора GCC:
g++ -o jdgen -O -DNDEBUG *.cpp
Утилита jdgen является утилитой командной строки и все аргументы получает через командную строку. Так же аргументы можно записывать в т.н. response-файлы, а их имена специальным образом указывать в командной строке.
Аргументы jdgen, указываемые в командной строке и response-файлах должны следовать следующим правилам:
Аргументы утилиты jdgen:
В утилите jdgen реализован достаточно тривиальный анализатор javadoc-комментариев. Javadoc-комментарий просматривается посимвольно. Лидирующие пробелы и символы * в начале каждой строки игнорируются. Все, что найдено до первого символа @ сохраняется как текст комментария. Все, что найдено после символа @ рассмативается как содержимое javadoc-тега. Содержимым javadoc-тега является часть от символа @ до следующего символа @ или от символа @ до конца комментария.
Это приводит к тому, что jdgen успешно обрабатывает, все javadoc-теги, начинающиеся с символа @. Но jdgen не корректно обрабатывает теги {@dooRoot} и {@link}.