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