Разрабатываем iDoc

Третий этап работы, подготовкой для которого были выбор инструментов и проектирование интерфейса, предполагает непосредственно создание генератора HTML-страниц. С этой целью нужно создать простой doclet, который может использоваться со стандартной утилитой javadoc от Sun. Для этого можно использовать пакеты java, однако iDoc также для всех файлов с исходным кодом может генерировать документацию. В частности, для исходного кода OpenJDK можно сгенерировать Javadoc, поскольку данная библиотека является общедоступной и имеет лицензию GPL V2 (GNU Public License).

Весь порядок генерирования Javadoc в iDoc состоит в интегрировании по списку пакетов и классов и предполагает вызов методов статического HTML в описанном ранее формате. В листинге 4 приведены методы вывода текста на итоговую страницу.

Листинг 4. Код doclet'a, генерирующий детальные HTML-страницы

private void printDetail(PrintStream p, ProgramElementDoc doc,

String id, String name) {

divHeader(p, id, name, "panel");

textHeader(p, null);

textRow(p, getSignature(doc));

textRow(p, getCommentText(doc.commentText()));

textFooter(p);

if (doc instanceof ExecutableMemberDoc) {

printMethodDetail(p, (ExecutableMemberDoc) doc);

  }

divFooter(p);

}

 

private void printMethodDetail(PrintStream p, ExecutableMemberDoc field) {

if (field.parameters().length > 0) {

textHeader(p, "Parameters");

for (int i=0; i<field.paramTags().length; i++) {

textRow(p, "<b>" + field.parameters()[i].typeName() + " "

+ field.paramTags()[i].parameterName()

+ "</b>: "

+ getCommentText(field.paramTags()[i].parameterComment()));

  }

textFooter(p);

}

if (field.throwsTags().length > 0) {

textHeader(p, "Throws");

for (int i=0; i<field.throwsTags().length; i++) {

textRow(p, "<b>" + field.throwsTags()[i].exceptionName()

+ "</b>: "

+ getCommentText(field.throwsTags()[i].exceptionComment()));

     }

textFooter(p);

  }

}

 

Приведенный код создан так, чтобы генерирование документации для классов, полей, конструкторов и методов осуществлялось с помощью метода printDetail (). Для конструкторов и методов, при этом, дополнительно выводятся данные о параметрах и исключениях, т.к. представлены они в виде объектов классов-наследников ExecutableMemberDoc.

Проблемы с производительностью

Отладка генерируемых файлов упрощается благодаря наличию режима предварительного просмотра приложений iPhone в Aptana. После каждой интеграции можно обнаружить все расхождения между выводимыми файлами и ранее спроектированным интерфейсом. Недостаток состоит в том, что проблемы с производительностью при использовании данного режима остаются незамеченными. Это связано с тем, что скорость работы современных компьютеров в 3 – 5 раз выше, чем скорость iPhone, который снабжен процессором ARM с частотой 620 МГц. Кроме этого, данные на iPhone часто загружаются с использованием медленного мобильного интернета. Поэтому обязательно нужно запускать созданное приложение на реальном iPhone.

К примеру, тестирование iDoc на iPhone показывает, что при генерировании одного большого HTML-файла появляются необычные визуальные эффекты и снижается производительность работы. Решить эту проблему можно, создав один главный файл для навигации по названиям пакетов и именам классов и несколько отдельных файлов, в которых будут содержаться комментарии и детальная информация о методах для каждого класса. Код описан в листинге 5. В итоге будет создано много файлов небольшого размера, что положительно отразится на производительности.

Листинг 5. Doclet изучает все пакеты и создает для каждого класса отдельные файлы документации

out = new FileOutputStream(index);

p = new PrintStream(out);

printHeader(p);

 

PackageDoc[] packages = root.specifiedPackages();

Arrays.sort(packages);

 

printPackages(p, packages);

 

for (int i=0; i<packages.length; i++) {

printPackageDetail(p, packages[i]);

}

for (int i=0; i<packages.length; i++) {

ClassDoc[] classes = packages[i].allClasses();

Arrays.sort(classes);

for (int j=0; j<classes.length; j++) {

// Creating a separate file for each class.

PrintStream p2 = new PrintStream(new FileOutputStream(getFilename(classes[j])));

printClassDetail(p2, classes[j]);

p2.close();

  }

}

printFooter(p);

p.close();