Пакет jdk.javadoc.doclet

API Doclet предоставляет среду, которая, в сочетании с API Модели Языка и API Дерева Компилятора, позволяет клиентам инспектировать структуры программ и библиотек на уровне исходного кода, включая комментарии API, встроенные в исходный код.

standard doclet может использоваться для генерации документации в формате HTML. Он поддерживает пользовательские taglets, которые могут использоваться для генерации настраиваемого вывода для пользовательских тегов в комментариях к документации.

Примечание: Объявления в этом пакете заменяют объявления в более старом пакете com.sun.javadoc. Подробную информацию о сопоставлении старых типов с новыми типами см. в Руководстве по миграции.

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

Вызов определяется интерфейсом Doclet — метод интерфейса run определяет точку входа.

    public boolean run(DocletEnvironment environment)
 

Экземпляр DocletEnvironment содержит среду, в которой будет инициализирован doclet. Из этой среды можно извлечь всю остальную информацию в виде elements. Кроме того, можно использовать API и утилиты, описанные в Language Model API, для запроса элементов и типов.

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

Выбранный

Элемент считается выбранным, если управление выбором разрешает его документирование. (Обратите внимание, что синтетические элементы никогда не выбираются.)

Указанный

Набор элементов, указанный пользователем, считается указанными элементами. Указанные элементы служат отправной точкой для определения включенных элементов, которые будут документированы.

Включенный

Элемент считается включённым, если он указан, если он содержит указанный элемент или он заключён в указанный элемент и выбран. Включенные элементы будут документированы.

Параметры

Управление выбором javadoc можно указать с помощью следующих параметров:

• --show-members:value и --show-types:value могут использоваться для фильтрации членов со следующими значениями:
  • public — рассматриваются только публичные элементы
  • protected — рассматриваются публичные и защищённые элементы
  • package — рассматриваются публичные, защищённые и пакеты-элементы
  • private — рассматриваются все элементы
• --show-packages:value "exported" или "all" могут использоваться для рассмотрения только экспортированных пакетов или всех пакетов в модуле.
• --show-module-contents:value может использоваться для указания уровня, на котором могут документироваться объявления модулей. Значение "api" указывает документацию уровня API, а "all" указывает подробную документацию.

Следующие параметры могут использоваться для указания элементов, которые необходимо документировать:

• --module документирует указанные модули.
• --expand-requires:value расширяет набор документируемых модулей, включив некоторые или все зависимости модулей. Значение может быть одним из:
  • transitive — каждый явно указанный в командной строке модуль расширяется, включая замыкание его транзитивных зависимостей
  • all — каждый явно указанный в командной строке модуль расширяется, включая замыкание его транзитивных зависимостей, а также все его прямые зависимости
  По умолчанию рассматриваются только указанные модули без расширения зависимостей модулей.
• packagenames может использоваться для указания пакетов.
• -subpackages может использоваться для рекурсивной загрузки пакетов.
• -exclude может использоваться для исключения директорий пакетов.
• sourcefilenames может использоваться для указания имён файлов исходного кода.

Взаимодействие со старыми параметрами.

Новые --show-* параметры обеспечивают более подробную замену старым параметрам -public, -protected, -package, -private. В качестве альтернативы, старые параметры могут продолжать использоваться как сокращения для комбинаций новых параметров, как описано ниже:

Сопоставление параметров сокращённой формы

Старый параметр	Эквивалентно этим значениям с новым параметром
	--show-members	--show-types	--show-packages	--show-module-contents
-public	public	public	exported	api
-protected	protected	protected	exported	api
-package	package	package	all	all
-private	private	private	all	all

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

Пример

Следующий пример doclet отображает информацию о классе и его членах, поддерживая параметр.

 // note imports deleted for clarity
 public class Example implements Doclet {
    Reporter reporter;
    @Override
    public void init(Locale locale, Reporter reporter) {
        reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
        this.reporter = reporter;
    }

    public void printElement(DocTrees trees, Element e) {
        DocCommentTree docCommentTree = trees.getDocCommentTree(e);
        if (docCommentTree != null) {
            System.out.println("Element (" + e.getKind() + ": "
                    + e + ") has the following comments:");
            System.out.println("Entire body: " + docCommentTree.getFullBody());
            System.out.println("Block tags: " + docCommentTree.getBlockTags());
        }
    }

    @Override
    public boolean run(DocletEnvironment docEnv) {
        reporter.print(Kind.NOTE, "overviewfile: " + overviewfile);
        // get the DocTrees utility class to access document comments
        DocTrees docTrees = docEnv.getDocTrees();

        // location of an element in the same directory as overview.html
        try {
            Element e = ElementFilter.typesIn(docEnv.getSpecifiedElements()).iterator().next();
            DocCommentTree docCommentTree
                    = docTrees.getDocCommentTree(e, overviewfile);
            if (docCommentTree != null) {
                System.out.println("Overview html: " + docCommentTree.getFullBody());
            }
        } catch (IOException missing) {
            reporter.print(Kind.ERROR, "No overview.html found.");
        }

        for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
            System.out.println(t.getKind() + ":" + t);
            for (Element e : t.getEnclosedElements()) {
                printElement(docTrees, e);
            }
        }
        return true;
    }

    @Override
    public String getName() {
        return "Example";
    }

    private String overviewfile;

    @Override
    public Set<? extends Option> getSupportedOptions() {
        Option[] options = {
            new Option() {
                private final List<String> someOption = Arrays.asList(
                        "-overviewfile",
                        "--overview-file",
                        "-o"
                );

                @Override
                public int getArgumentCount() {
                    return 1;
                }

                @Override
                public String getDescription() {
                    return "an option with aliases";
                }

                @Override
                public Option.Kind getKind() {
                    return Option.Kind.STANDARD;
                }

                @Override
                public List<String> getNames() {
                    return someOption;
                }

                @Override
                public String getParameters() {
                    return "file";
                }

                @Override
                public boolean process(String opt, List<String> arguments) {
                    overviewfile = arguments.get(0);
                    return true;
                }
            }
        };
        return new HashSet<>(Arrays.asList(options));
    }

    @Override
    public SourceVersion getSupportedSourceVersion() {
        // support the latest release
        return SourceVersion.latest();
    }
 }
 

Этот doclet можно вызвать с помощью командной строки, например:

     javadoc -doclet Example \
       -overviewfile overview.html \
       -sourcepath source-location \
       source-location/Example.java
 

Руководство по миграции

Многие типы в старом API com.sun.javadoc не имеют эквивалентов в этом пакете. Вместо этого используются типы в API javax.lang.model и com.sun.source.

В следующей таблице приводится руководство по сопоставлению старых типов с их заменами. В некоторых случаях прямой эквивалент отсутствует.

Руководство по отображению старых типов на новые типы

Старый тип	Новый тип
AnnotatedType	javax.lang.model.type.TypeMirror
AnnotationDesc	javax.lang.model.element.AnnotationMirror
AnnotationDesc.ElementValuePair	javax.lang.model.element.AnnotationValue
AnnotationTypeDoc	javax.lang.model.element.TypeElement
AnnotationTypeElementDoc	javax.lang.model.element.ExecutableElement
AnnotationValue	javax.lang.model.element.AnnotationValue
ClassDoc	javax.lang.model.element.TypeElement
ConstructorDoc	javax.lang.model.element.ExecutableElement
Doc	javax.lang.model.element.Element
DocErrorReporter	jdk.javadoc.doclet.Reporter
Doclet	jdk.javadoc.doclet.Doclet
ExecutableMemberDoc	javax.lang.model.element.ExecutableElement
FieldDoc	javax.lang.model.element.VariableElement
LanguageVersion	javax.lang.model.SourceVersion
MemberDoc	javax.lang.model.element.Element
MethodDoc	javax.lang.model.element.ExecutableElement
PackageDoc	javax.lang.model.element.PackageElement
Parameter	javax.lang.model.element.VariableElement
ParameterizedType	javax.lang.model.type.DeclaredType
ParamTag	com.sun.source.doctree.ParamTree
ProgramElementDoc	javax.lang.model.element.Element
RootDoc	jdk.javadoc.doclet.DocletEnvironment
SeeTag	com.sun.source.doctree.LinkTree com.sun.source.doctree.SeeTree
SerialFieldTag	com.sun.source.doctree.SerialFieldTree
SourcePosition	com.sun.source.util.SourcePositions
Tag	com.sun.source.doctree.DocTree
ThrowsTag	com.sun.source.doctree.ThrowsTree
Type	javax.lang.model.type.TypeMirror
TypeVariable	javax.lang.model.type.TypeVariable
WildcardType	javax.lang.model.type.WildcardType