Пакет jdk.javadoc.doclet
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.
В следующей таблице представлено руководство по сопоставлению старых типов с их заменителями. В некоторых случаях прямой эквивалент отсутствует.
- Since:
- 9
- См. также:
| Класс | Описание |
|---|---|
| Doclet | Пользовательский doclet должен реализовать этот интерфейс, как описано в описании пакета. |
| Doclet.Option | Инкапсуляция имени опции, псевдонимов, параметров и описаний, используемых Doclet. |
| Doclet.Option.Kind | Вид опции. |
| DocletEnvironment | Представляет операционную среду одного вызова doclet. |
| DocletEnvironment.ModuleMode | Режим, определяющий уровень детализации документации модуля. |
| Reporter | Интерфейс для сообщения о диагностических и других сообщениях. |
| StandardDoclet | Этот doclet генерирует документацию в формате HTML для указанных модулей, пакетов и типов. |
| Taglet | Интерфейс для пользовательского taglet, поддерживаемого такими doclet, как standard doclet. |
| Taglet.Location | Вид местоположения, в котором может использоваться метка. |
© 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://download.java.net/java/early_access/jdk24/docs/api/jdk.javadoc/jdk/javadoc/doclet/package-summary.html