Spec-Zone.ru › OpenJDK 21

Пакет jdk.javadoc.doclet

package 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 {
    private Reporter reporter;
    private PrintWriter stdout;

    @Override
    public void init(Locale locale, Reporter reporter) {
        reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
        this.reporter = reporter;
        stdout = reporter.getStandardWriter();
    }

    public void printElement(DocTrees trees, Element e) {
        DocCommentTree docCommentTree = trees.getDocCommentTree(e);
        if (docCommentTree != null) {
            stdout.println("Element (" + e.getKind() + ": "
                    + e + ") has the following comments:");
            stdout.println("Entire body: " + docCommentTree.getFullBody());
            stdout.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) {
                stdout.println("Overview html: " + docCommentTree.getFullBody());
            }
        } catch (IOException missing) {
            reporter.print(Kind.ERROR, "No overview.html found.");
        }

        for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
            stdout.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 = List.of(
                        "--overview-file",
                        "-overviewfile",
                        "-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 Set.of(options);
    }

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

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

javadoc -docletpath doclet-classes \
  -doclet Example \
  --overview-file overview.html \
  --source-path source-location \
  source-location/Example.java

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

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

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

END_OF_DOCUMENT_MARKER
Руководство по отображению старых типов на новые типы
Старый тип Новый тип
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
Since:
9
См. также:
  • Doclet
  • DocletEnvironment
Класс Описание
Doclet
Пользовательский doclet должен реализовать этот интерфейс, как описано в описании пакета.
Doclet.Option
Инкапсулирует имя параметра, псевдонимы, параметры и описания, используемые Doclet.
Doclet.Option.Kind
Вид параметра.
DocletEnvironment
Представляет рабочую среду одного вызова doclet.
DocletEnvironment.ModuleMode
Режим, определяющий уровень подробности документации модуля.
Reporter
Интерфейс для отчётности о диагностике и других сообщениях.
StandardDoclet
Этот doclet генерирует HTML-документацию для указанных модулей, пакетов и типов.
Taglet
Интерфейс для пользовательского taglet, поддерживаемого doclet, такого как standard doclet.
Taglet.Location
Вид местоположения, в котором может быть использован тег.

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.javadoc/jdk/javadoc/doclet/package-summary.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API