Spec-Zone .ru
спецификации, руководства, описания, API
|
|
Spec-Zone .ru
спецификации, руководства, описания, API
|
Вот основные шаги, за которыми Вы должны следовать, чтобы создать и использовать Ваш собственный doclet:
Если Вы выполните javadoc без параметра командной строки -doclet, то он примет значение по умолчанию к стандарту doclet, чтобы произвести документацию API формата HTML.
Пакет com.sun.javadoc состоит из интерфейсов, которые определяют doclet API. Файл lib/tools.jar в Java, 2 SDK содержат эти интерфейсы и также частный пакет с классами, которые реализуют интерфейсы. Файл tools.jar также содержит классы, реализовывая стандарт doclet.
import com.sun.javadoc.*;
public class ListClass {
public static boolean start(RootDoc root) {
ClassDoc[] classes = root.classes();
for (int i = 0; i < classes.length; ++i) {
System.out.println(classes[i]);
}
return true;
}
}
Поскольку Вы могли бы быть в состоянии предположить, смотря на код, этот doclet берет уроки, на которые Javadoc управляет и печатает их имена к стандарту. Эта первая вещь заметить о doclet состоит в том, что он импортирует com.sun.javadoc пакет, чтобы использовать doclet API. Как со всем doclets, точка входа является методом public static boolean start. Метод start берет RootDoc в качестве параметра. Этот параметр переносит информацию о любых опциях, определенных на командной строке, когда javadoc выполняется, и также о классах и пакетах, на которые работает javadoc.
RootDoc определяет метод classes, который возвращает массив ClassDoc, элементы которого представляют классы тот Javadoc синтаксические анализы. Цикл for тогда распечатывает имена каждого class в массиве. (Передача ClassDoc к println приводит к печати имени class, который представляет ClassDoc.)
Чтобы выполнить этот doclet, сначала необходимо скомпилировать это. Можно скомпилировать это с javac компилятором. doclet API classfiles находится в файле lib/tools.jar в Java 2 SDK, которые автоматически не загружает javac. Вы поэтому должны включать tools.jar на пути к классу компилятора, как в этом примере:
javac -classpath C:\jdk1.3\lib\tools.jar ListClass.javaЧтобы выполнить ListClass doclet, Вы указываете на скомпилированный doclet с -doclet Джейвэдока и тегами -docletpath. Например, чтобы выполнить doclet на файле под названием MyClass.java, Вы могли использовать эту команду, предполагая, что ListClass.class находится в текущем каталоге:
% javadoc -doclet ListClass -docletpath . MyClass.javaВывод будет строкой "MyClass". Отметьте, что эта команда не требует, чтобы tools.jar был на пути class, поскольку инструмент Javdoc автоматически загружает это.
Примечание о параметрах командной строки: Если Вы выполните javadoc -help, то Вы будете видеть, что у инструмента Javadoc есть два набора параметров командной строки. Один набор универсален и будет работать с любым doclet. Второй набор опций является особенным для стандарта doclet. Опции в этом втором наборе не будут доступны при использовании пользовательского doclets. Ваш пользовательский doclets может также определить их собственные параметры командной строки. См. пример ниже.
Чтобы генерировать документацию API, doclet должен будет быть значительно более сложным чем этот простой пример. Если Вы хотите настроить формат документации API, сгенерированной Javadoc, можно хотеть запустить со стандарта значения по умолчанию doclet и изменить его по мере необходимости, а не записать Ваш собственный doclet с нуля.
Для примера см.
method.tags("mytag")
возвратил бы массив объектов Tag, представляющих любые теги @mytag в комментарии для документации метода. Можно тогда получить доступ к информации в своих тегах @mytag с
методом text Tag. Тот метод возвращает строку, представляющую контент тега, который можно проанализировать или использовать как необходимый. Например, если комментарий для документации, содержавший один из Ваших пользовательских тегов как это: @mytag Some dummy text.тогда метод text возвратил бы строку "Some dummy text.".
Вот автономный doclet (не подкласс стандарта doclet), который использует эти идеи распечатать текст, связанный со всеми экземплярами указанного тега, который это находит в комментариях метода. Это могло быть расширено, чтобы найти все экземпляры того тега во всех комментариях.
import com.sun.javadoc.*;
public class ListTags {
public static boolean start(RootDoc root){
String tagName = "mytag";
writeContents(root.classes(), tagName);
return true;
}
private static void writeContents(ClassDoc[] classes, String tagName) {
for (int i=0; i < classes.length; i++) {
boolean classNamePrinted = false;
MethodDoc[] methods = classes[i].methods();
for (int j=0; j < methods.length; j++) {
Tag[] tags = methods[j].tags(tagName);
if (tags.length > 0) {
if (!classNamePrinted) {
System.out.println("\n" + classes[i].name() + "\n");
classNamePrinted = true;
}
System.out.println(methods[j].name());
for (int k=0; k < tags.length; k++) {
System.out.println(" " + tags[k].name() + ": "
+ tags[k].text());
}
}
}
}
}
}
Тег, который ищет этот doclet, определяется переменным tagName. Значение строки tagName может быть любым именем тега, пользовательским или стандартным. Этот doclet пишет в стандарт, но его выходной формат мог быть изменен, например, чтобы записать вывод HTML в файл. У любого doclet, который использует пользовательские опции, должен быть метод под названием optionLength(String option), который возвращает int. Для каждой пользовательской опции, которую Вы хотите, чтобы Ваш doclet распознал, optionLength должен возвратить число отдельных частей или маркеров в опции. Для нашего примера мы хотим быть в состоянии использовать пользовательскую опцию формы -tag mytag. У этой опции есть две части, опция -tag непосредственно и ее значение, таким образом, метод optionLength в нашем doclet должен возвратить 2 для опции -tag. Метод optionsLength должен возвратить 0 для нераспознанных опций.
Вот полный, увеличенный doclet:
import com.sun.javadoc.*;
public class ListTags {
public static boolean start(RootDoc root){
String tagName = readOptions(root.options());
writeContents(root.classes(), tagName);
return true;
}
private static void writeContents(ClassDoc[] classes, String tagName) {
for (int i=0; i < classes.length; i++) {
boolean classNamePrinted = false;
MethodDoc[] methods = classes[i].methods();
for (int j=0; j < methods.length; j++) {
Tag[] tags = methods[j].tags(tagName);
if (tags.length > 0) {
if (!classNamePrinted) {
System.out.println("\n" + classes[i].name() + "\n");
classNamePrinted = true;
}
System.out.println(methods[j].name());
for (int k=0; k < tags.length; k++) {
System.out.println(" " + tags[k].name() + ": " + tags[k].text());
}
}
}
}
}
private static String readOptions(String[][] options) {
String tagName = null;
for (int i = 0; i < options.length; i++) {
String[] opt = options[i];
if (opt[0].equals("-tag")) {
tagName = opt[1];
}
}
return tagName;
}
public static int optionLength(String option) {
if(option.equals("-tag")) {
return 2;
}
return 0;
}
public static boolean validOptions(String options[][],
DocErrorReporter reporter) {
boolean foundTagOption = false;
for (int i = 0; i < options.length; i++) {
String[] opt = options[i];
if (opt[0].equals("-tag")) {
if (foundTagOption) {
reporter.printError("Only one -tag option allowed.");
return false;
} else {
foundTagOption = true;
}
}
}
if (!foundTagOption) {
reporter.printError("Usage: javadoc -tag mytag -doclet ListTags ...");
}
return foundTagOption;
}
}
В этом изменил doclet, переменный tagName устанавливается с параметром командной строки -tag. У этого есть возвраты метода optionLength два для нашей пользовательской опции. Отметьте, что явный звонок в optionLength не требуется. Этот doclet также добавляет методы readOptions, который фактически анализирует параметры командной строки, ища опцию -tag. Это использует факт, что метод Rootdoc.options возвращает двумерный Строковый массив, содержащий информацию об опции. Например, учитывая команду
javadoc -foo this that -bar other ...метод RootDoc.options возвратится
options()[0][0] = "-foo" options()[0][1] = "this" options()[0][2] = "that" options()[1][0] = "-bar" options()[1][1] = "other"Число элементов в секунду массива индексирует, определяется методом optionLength. В этом примере optionLength возвращает 3 для опции -foo и возвращает 2 для опции -bar.
Метод validOptions является дополнительным методом, который можно использовать, чтобы протестировать законность использования тегов командной строки. Если метод validOptions присутствует, он автоматически вызывается; Вы не должны явно вызвать это. Это должно возвратить true, если использование опции допустимо, и false иначе. Можно также напечатать соответствующие сообщения об ошибках от validOptions, когда неподходящие использования параметров командной строки находятся. Метод validOptions в этом примере doclet проверяет, что опция -tag используется однажды и только однажды.
