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 только проверить файл, не изменяя его.

Пример применения 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).

Компиляция с использованием mxx

Утилита 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

Hosted by uCoz

Аргументы командной строки

Утилита jdgen является утилитой командной строки и все аргументы получает через командную строку. Так же аргументы можно записывать в т.н. response-файлы, а их имена специальным образом указывать в командной строке.

Аргументы jdgen, указываемые в командной строке и response-файлах должны следовать следующим правилам:

Аргументы утилиты jdgen:

-f <имя_файла>
указывает имя файла для обработки. Имя файла не может быть маской имен файлов. Если необходимо обработать несколько файлов, следует указать несколько аргументов -f.
-checkonly
указывает jdgen только осуществить проверку, но не изменять входные файлы.
-fixme <текст>
указывает подстроку, которую следует искать в javadoc комментариях.
-checkfixme
указывает осуществлять поиск подстроки в javadoc комментариях. Искомая подстрока определяется аргументом -fixme. Если аргумент -fixme не указан, то ищется подстрока FIX ME.
-missingjavadoc <текст>
назначает текст, который будет подставляться в заглушку для отсутствующего javadoc комментария. Если этот аргумент отсутствует, то в заглушку будет помещаться текст по умолчанию.
-missingparam <текст>
назначает текст, который будет подставляться в заглушку для отсутствующего javadoc тега @param. Если этот аргумент отсутствует, то в заглушку будет помещаться текст по умолчанию.
-missingreturn <текст>
назначает текст, который будет подставляться в заглушку для отсутствующего javadoc тега @return. Если этот аргумент отсутствует, то в заглушку будет помещаться текст по умолчанию.
-missingthrows <текст>
назначает текст, который будет подставляться в заглушку для отсутствующего javadoc тега @throws. Если этот аргумент отсутствует, то в заглушку будет помещаться текст по умолчанию.

Ограничения

В утилите jdgen реализован достаточно тривиальный анализатор javadoc-комментариев. Javadoc-комментарий просматривается посимвольно. Лидирующие пробелы и символы * в начале каждой строки игнорируются. Все, что найдено до первого символа @ сохраняется как текст комментария. Все, что найдено после символа @ рассмативается как содержимое javadoc-тега. Содержимым javadoc-тега является часть от символа @ до следующего символа @ или от символа @ до конца комментария.

Это приводит к тому, что jdgen успешно обрабатывает, все javadoc-теги, начинающиеся с символа @. Но jdgen не корректно обрабатывает теги {@dooRoot} и {@link}.

Hosted by uCoz