Spec-Zone.ru › OpenJDK 25

Пакет 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.

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

Соответствие старых типов новым типам
Старый тип Новый тип
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
Начиная с:
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
Тип места, в котором может использоваться тег.

Сообщить об ошибке или предложить улучшение
Дополнительную справочную информацию по API и документацию для разработчиков см. в разделе Документация Java SE, где представлены более подробные описания для разработчиков, включая концептуальные обзоры, определения терминов, обходные решения и примеры работающего кода. Другие версии.
Java является товарным знаком или зарегистрированным товарным знаком Oracle и/или ее аффилированных лиц в США и других странах.
Авторские права © 1993, 2025, Oracle и/или ее аффилированные лица, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.
Все права защищены. Использование регулируется условиями лицензии и политикой распространения документации.

© 1993, 2025, 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/25/docs/api/jdk.javadoc/jdk/javadoc/doclet/package-summary.html

Spec-Zone.ru

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