Spec-Zone .ru
спецификации, руководства, описания, API
Содержание документации

Краткий обзор Doclet

Содержание

Основы

Doclets являются программами, записанными в языке программирования Java™, которые используют doclet API, чтобы определить контент и формат вывода инструмента Javadoc. По умолчанию инструмент Javadoc использует "стандарт" doclet обеспеченный Sun™, чтобы генерировать документацию API в HTML-форме. Однако, можно предоставить свой собственный doclets, чтобы настроить вывод Javadoc, как Вам нравится. Можно записать doclets, с нуля используя doclet API, или можно запустить со стандарта doclet и изменить его, чтобы удовлетворить Вашим потребностям.

Вот основные шаги, за которыми Вы должны следовать, чтобы создать и использовать Ваш собственный doclet:

  1. Запишите программу Java, которая составляет Ваш doclet. Ваша программа должна импортировать com.sun.javadoc.*, чтобы использовать doclet API. Точка входа Вашей программы является классом с методом public static boolean start, который берет RootDoc в качестве параметра.
  2. Скомпилируйте свой doclet. Можно использовать компилятор в Java 2 SDK, javac.
  3. Выполните javadoc инструмент, используя -doclet startingclass опция, чтобы произвести вывод, определенный Вашим doclet, где startingclass является полностью определенным именем запускающегося класса, упомянутого в шаге 1 выше.
doclet файлы класса API находятся в файле lib/tools.jar в SDK. Когда Вы компилируете doclet, tools.jar должен быть на пути к классу. Можно использовать опцию -classpath на javac с этой целью.

Если Вы выполните javadoc без параметра командной строки -doclet, то он примет значение по умолчанию к стандарту doclet, чтобы произвести документацию API формата HTML.

Пакет com.sun.javadoc состоит из интерфейсов, которые определяют doclet API. Файл lib/tools.jar в Java, 2 SDK содержат эти интерфейсы и также частный пакет с классами, которые реализуют интерфейсы. Файл tools.jar также содержит классы, реализовывая стандарт doclet.

Простой Пример Doclet

Можно получить чувство для пути doclets работа, смотря на этот простой пример 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 тогда распечатывает имена каждого класса в массиве. (Передача ClassDoc к println приводит к печати имени класса, который представляет 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 был на пути к классу, поскольку инструмент Javdoc автоматически загружает это.

Примечание о параметрах командной строки: Если Вы выполните  javadoc -help, то Вы будете видеть, что у инструмента Javadoc есть два набора параметров командной строки. Один набор универсален и будет работать с любым doclet. Второй набор опций является особенным для стандарта doclet. Опции в этом втором наборе не будут доступны при использовании пользовательского doclets. Ваш пользовательский doclets может также определить их собственные параметры командной строки. См. пример ниже.

Чтобы генерировать документацию API, doclet должен будет быть значительно более сложным чем этот простой пример. Если Вы хотите настроить формат документации API, сгенерированной Javadoc, можно хотеть запустить со стандарта по умолчанию doclet и изменить его по мере необходимости, а не записать Ваш собственный doclet с нуля.

Пример - Разделение на подклассы Стандартного Doclet

Чтобы настроить вывод инструмента Javadoc, Вы должны записать свой собственный doclet, который определяет контент и формат вывода, которого Вы требуете. Если Вы хотите вывод HTML с примерно тем же самым форматом как вывод по умолчанию, можно использовать стандарт doclet в качестве начальной точки для того, чтобы создать Ваш doclet. Можно разделить соответствующие классы на подклассы в стандарте doclet и затем добавить или переопределить методы по мере необходимости, чтобы произвести вывод, который Вы хотите. Или можно скопировать целый стандарт doclet и изменить его. Если Вы используете копию стандарта doclet как Ваша начальная точка, можно хотеть удалить операторы package в начале каждого исходного файла и заменить их именем собственный, новый пакет.

Для примера см., Как я могу изменить стандарт doclet, чтобы произвести ссылки к исходному коду из документации API?

Пример - Создание и обработка пользовательских тегов

Предположите, например, что Вы хотите использование пользовательский тег, скажем @mytag, в Ваших комментариях для документации в дополнение к стандартным тегам как @param и @return. Чтобы использовать информацию в Ваших пользовательских тегах, у Вас должны быть свои экземпляры использования doclet Tag, которые представляют Ваши пользовательские теги. Один из самых легких способов сделать, который должен использовать метод tags(String) Doc или один из подклассов Doc. Этот метод возвращает массив объектов Tag, представляющих любые теги, имя которых соответствует строковый параметр. Например, если method является экземпляром MethodDoc, то
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 в файл.

Пример - Используя пользовательские параметры командной строки

Можно записать doclets, которые принимают пользовательские параметры командной строки. Чтобы видеть, как это работает, давайте увеличивать пример doclet выше так, чтобы он позволил Вам использовать параметр командной строки, чтобы определить имя тега к поиску.

У любого 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 используется однажды и только однажды.


Oracle и/или его филиалы Авторское право © 1993, 2011, Oracle и/или его филиалы. Все права защищены.
Свяжитесь с Нами