Module jdk.javadoc
Package jdk.javadoc.doclet
The Doclet API provides an environment which, in conjunction with
the Language Model API and Compiler Tree API, allows clients
to inspect the source-level structures of programs and
libraries, including API comments embedded in the source.
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)
The 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.
Terminology
- Selected
- An element is considered to be selected, if the selection controls allow it to be documented. (Note that synthetic elements are never selected.)
- Specified
- The set of elements specified by the user are considered to be specified elements. Specified elements provide the starting points for determining the included elements to be documented.
- Included
- An element is considered to be included, if it is specified if it contains a specified element, or it is enclosed in a specified element, and is selected. Included elements will be documented.
Options
Javadoc selection control can be specified with these options as follows:--show-members:valueand--show-types:valuecan be used to filter the members, with the following values:- public -- considers only public elements
- protected -- considers public and protected elements
- package -- considers public, protected and package private elements
- private -- considers all elements
--show-packages:value"exported" or "all" can be used to consider only exported packages or all packages within a module.--show-module-contents:valuecan 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.
--moduledocuments the specified modules.--expand-requires:valueexpand the set of modules to be documented by including some or all of the modules dependencies. The value may be one of:- transitive -- each module specified explicitly on the command line is expanded to include the closure of its transitive dependencies
- all -- each module specified explicitly on the command line is expanded to include the closure of its transitive dependencies, and also all of its direct dependencies
packagenamescan be used to specify packages.-subpackagescan be used to recursively load packages.-excludecan be used exclude package directories.sourcefilenamescan be used to specify source file names.
Interactions with older options.
The new--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.
Example
The following is an example doclet that displays information of a class and its members, supporting an option.
// note imports deleted for clarity
public class Example implements Doclet {
Reporter reporter;
@Override
public void init(Locale locale, Reporter reporter) {
reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
this.reporter = reporter;
}
public void printElement(DocTrees trees, Element e) {
DocCommentTree docCommentTree = trees.getDocCommentTree(e);
if (docCommentTree != null) {
System.out.println("Element (" + e.getKind() + ": "
+ e + ") has the following comments:");
System.out.println("Entire body: " + docCommentTree.getFullBody());
System.out.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) {
System.out.println("Overview html: " + docCommentTree.getFullBody());
}
} catch (IOException missing) {
reporter.print(Kind.ERROR, "No overview.html found.");
}
for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
System.out.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 = Arrays.asList(
"-overviewfile",
"--overview-file",
"-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 new HashSet<>(Arrays.asList(options));
}
@Override
public SourceVersion getSupportedSourceVersion() {
// support the latest release
return SourceVersion.latest();
}
}
This doclet can be invoked with a command line, such as:
javadoc -doclet Example \
-overviewfile overview.html \
-sourcepath source-location \
source-location/Example.java
Migration Guide
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.
- Since:
- 9
- See Also:
Doclet,DocletEnvironment
-
Interface Summary Interface 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.DocletEnvironment Represents the operating environment of a single invocation of the doclet.Reporter This interface provides error, warning and notice reporting.Taglet The interface for a custom taglet supported by doclets such as thestandard doclet. -
Class Summary Class Description StandardDoclet This doclet generates HTML-formatted documentation for the specified modules, packages and types. -
Enum Summary Enum Description Doclet.Option.Kind The kind of an option.DocletEnvironment.ModuleMode Taglet.Location The kind of location in which a tag may be used.