The standard doclet
can be used to generate HTML-formatted documentation. It supports user-defined taglets
, which can be used to generate customized output for user-defined tags in documentation comments.
Note: The declarations in this package supersede those in the older package com.sun.javadoc
. For details on the mapping of old types to new types, see the Migration Guide.
Doclets are invoked by javadoc and this API can be used to write out program information to files. For example, the standard doclet is invoked by default, to generate HTML documentation.
The invocation is defined by the interface Doclet
-- the run
interface method, defines the entry point.
public boolean run(DocletEnvironment environment)
DocletEnvironment
instance holds the environment that the doclet will be initialized with. From this environment all other information can be extracted, in the form of elements
. One can further use the APIs and utilities described by Language Model API
to query Elements and Types.
--show-members:value
and --show-types:value
can be used to filter the members, with the following values: --show-packages:value
"exported" or "all" can be used to consider only exported packages or all packages within a module. --show-module-contents:value
can be used to specify the level at module declarations could be documented. A value of "api" indicates API level documentation, and "all" indicates detailed documentation. --module
documents the specified modules. --expand-requires:value
expand the set of modules to be documented by including some or all of the modules dependencies. The value may be one of: packagenames
can be used to specify packages. -subpackages
can be used to recursively load packages. -exclude
can be used exclude package directories. sourcefilenames
can be used to specify source file names. --show-*
options provide a more detailed replacement for the older options -public
, -protected
, -package
, -private
. Alternatively, the older options can continue to be used as shorter forms for combinations of the new options, as described below: Older option | Equivalent to these values with the new option | ||||
---|---|---|---|---|---|
--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 |
A qualified element name is one that has its package name prepended to it, such as java.lang.String
. A non-qualified name has no package name, such as String
.
// 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();
}
}
This doclet can be invoked with a command line, such as:
javadoc -docletpath doclet-classes \
-doclet Example \
--overview-file overview.html \
--source-path source-location \
source-location/Example.java
Many of the types in the old com.sun.javadoc
API do not have equivalents in this package. Instead, types in the javax.lang.model
and com.sun.source
APIs are used instead.
The following table gives a guide to the mapping from old types to their replacements. In some cases, there is no direct equivalent.
Class | Description |
---|---|
Doclet | The user doclet must implement this interface, as described in the package description. |
Doclet.Option | An encapsulation of option name, aliases, parameters and descriptions as used by the Doclet. |
Doclet.Option.Kind | The kind of an option. |
DocletEnvironment | Represents the operating environment of a single invocation of the doclet. |
DocletEnvironment.ModuleMode | The mode specifying the level of detail of module documentation. |
Reporter | Interface for reporting diagnostics and other messages. |
StandardDoclet | This doclet generates HTML-formatted documentation for the specified modules, packages and types. |
Taglet | The interface for a custom taglet supported by doclets such as the standard doclet . |
Taglet.Location | The kind of location in which a tag may be used. |
© 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