Пакет com.sun.javadoc

Примечание: Объявления в этом пакете устарели и заменены объявлениями в пакете jdk.javadoc.doclet. Для получения дополнительной информации см. Руководство по миграции в документации этого пакета.

Документация API Doclet (также называемая Javadoc API) предоставляет механизм для клиентов, позволяющий инспектировать структуру программ и библиотек на уровне исходного кода, включая javadoc комментарии, встраиваемые в исходный код. Это полезно для документации, проверки программ, автоматической генерации кода и многих других инструментов.

Doclets вызываются командой javadoc и используют этот API для записи информации о программе в файлы. Например, стандартный doclet вызывается по умолчанию и записывает документацию в файлы HTML.

Вызов определяется абстрактным классом Doclet — точка входа — метод start:

public static boolean start(RootDoc root)

Инстанс RootDoc содержит корень информации о структуре программы. Из этого корня можно извлечь всю остальную информацию о структуре программы.

Терминология

При вызове javadoc вы передаёте имена пакетов и имена файлов исходного кода — они называются указанными пакетами и классами. Вы также передаёте опции Javadoc; опции управления доступом Javadoc (-public, -protected, -package, и -private) фильтруют элементы программы, создавая набор результатов, называемый включённым набором или набором «документированных» элементов. (Неотфильтрованный набор также доступен через allClasses(false).)

На протяжении всего API термин класс обычно является сокращением от «класс или интерфейс», как в: ClassDoc, allClasses() и findClass(String). В лишь нескольких других местах он означает «класс, в отличие от интерфейса», как в: Doc.isClass(). В этом втором значении этот API выделяет четыре типа классов: обычные классы, перечисления, ошибки и исключения. В описании каждого элемента программы в API подробно описывается, какое значение используется.

Имя полностью квалифицированного класса или интерфейса — это имя, к которому добавлено имя его пакета, например, java.lang.String. Неквалифицированное имя не содержит имени пакета, например, String.

Пример

Следующий пример doclet отображает информацию в тегах @param обработанных классов:

import com.sun.javadoc.*;

public class ListParams extends Doclet {

    public static boolean start(RootDoc root) {
        ClassDoc[] classes = root.classes();
        for (int i = 0; i < classes.length; ++i) {
            ClassDoc cd = classes[i];
            printMembers(cd.constructors());
            printMembers(cd.methods());
        }
        return true;
    }

    static void printMembers(ExecutableMemberDoc[] mems) {
        for (int i = 0; i < mems.length; ++i) {
            ParamTag[] params = mems[i].paramTags();
            System.out.println(mems[i].qualifiedName());
            for (int j = 0; j < params.length; ++j) {
                System.out.println("   " + params[j].parameterName()
                    + " - " + params[j].parameterComment());
            }
        }
    }
}

Интерфейсы и методы из Javadoc API отмечены красным цветом. Doclet — это абстрактный класс, определяющий интерфейс вызова для doclets, Doclet содержит информацию о классе или интерфейсе, ExecutableMemberDoc — это суперинтерфейс для MethodDoc и ConstructorDoc, а ParamTag содержит информацию из тегов «@param».

Этот doclet при вызове с командной строкой типа:

javadoc -doclet ListParams -sourcepath <source-location> java.util

выводит результат типа:

...
    java.util.ArrayList.add
       index - index at which the specified element is to be inserted.
       element - element to be inserted.
    java.util.ArrayList.remove
       index - the index of the element to removed.
    ...