Пакет 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.
В следующей таблице приведено соответствие старых типов их заменам. В некоторых случаях прямого эквивалента нет.
- Начиная с:
- 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://docs.oracle.com/en/java/javase/25/docs/api/jdk.javadoc/jdk/javadoc/doclet/package-summary.html