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.
--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 { 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
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.
Old Type | New Type |
---|---|
AnnotatedType | javax.lang.model.type.Type |
AnnotationDesc | javax.lang.model.element.AnnotationMirror |
AnnotationDesc.ElementValuePair | javax.lang.model.element.AnnotationValue |
AnnotationTypeDoc | javax.lang.model.element.TypeElement |
AnnotationTypeElementDoc | javax.lang.model.element.ExecutableElement |
AnnotationValue | javax.lang.model.element.AnnotationValue |
ClassDoc | javax.lang.model.element.TypeElement |
ConstructorDoc | javax.lang.model.element.ExecutableElement |
Doc | javax.lang.model.element.Element |
DocErrorReporter | jdk.javadoc.doclet.Reporter |
Doclet | jdk.javadoc.doclet.Doclet |
ExecutableMemberDoc | javax.lang.model.element.ExecutableElement |
FieldDoc | javax.lang.model.element.VariableElement |
LanguageVersion | javax.lang.model.SourceVersion |
MemberDoc | javax.lang.model.element.Element |
MethodDoc | javax.lang.model.element.ExecutableElement |
PackageDoc | javax.lang.model.element.PackageElement |
Parameter | javax.lang.model.element.VariableElement |
ParameterizedType | javax.lang.model.type.DeclaredType |
ParamTag | com.sun.source.doctree.ParamTree |
ProgramElementDoc | javax.lang.model.element.Element |
RootDoc | jdk.javadoc.doclet.DocletEnvironment |
SeeTag | com.sun.source.doctree.LinkTree com.sun.source.doctree.SeeTree |
SerialFieldTag | com.sun.source.doctree.SerialFieldTree |
SourcePosition | com.sun.source.util.SourcePositions |
Tag | com.sun.source.doctree.DocTree |
ThrowsTag | com.sun.source.doctree.ThrowsTree |
Type | javax.lang.model.type.Type |
TypeVariable | javax.lang.model.type.TypeVariable |
WildcardType | javax.lang.model.type.WildcardType |
Doclet
,
DocletEnvironment
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.
|
Enum | Description |
---|---|
Doclet.Option.Kind |
The kind of an option.
|
DocletEnvironment.ModuleMode |
Submit a bug or feature
Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.
Copyright © 1993, 2016, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-Ubuntu+0-9b147-1