See: Description
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.
|
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 javax.lang.model
elements. One can further use the
APIs and utilities described by javax.lang.model
to query Elements and Types.
-public
, -protected
, -package
,
and -private
) are used to filter program elements, producing a
result set, called the included set, or "selected" set.
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
.
import com.sun.source.doctree.DocCommentTree; import com.sun.source.util.DocTrees; import java.io.IOException; import java.util.Collections; import java.util.Set; import javax.lang.model.SourceVersion; import javax.lang.model.element.Element; import javax.lang.model.element.TypeElement; import jdk.javadoc.doclet.*; public class Example implements Doclet { @Override public void init(Locale locale, Reporter reporter) { return; } @Override public boolean run(RootDoc root) { // cache the DocTrees utility class to access DocComments DocTrees docTrees = root.getDocTrees(); // location of an element in the same directory as overview.html try { Element barElement = null; for (Element e : root.getIncludedClasses()) { if (e.getSimpleName().toString().equals("FooBar")) { barElement = e; } } DocCommentTree docCommentTree = docTrees.getDocCommentTree(barElement, "overview.html"); if (docCommentTree != null) { System.out.println("Overview html: " + docCommentTree.getFullBody()); } } catch (IOException missing) { System.err.println("No overview.html found."); } for (TypeElement t : root.getIncludedClasses()) { System.out.println(t.getKind() + ":" + t); for (Element e : t.getEnclosedElements()) { DocCommentTree docCommentTree = docTrees.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()); } else { System.out.println("no comment."); } } } return true; } @Override public String getName() { return "Example"; } private String someOption; @Override public Set<Option> getSupportedOptions() { Option[] options = { new Option() { public int getArgumentCount() { return 1; } public String getDescription() { return "someoption"; } public Option.Kind getKind() { return Option.Kind.STANDARD; } public String getName() { return "someoption"; } public String getParameters() { return "url"; } public boolean matches(String option) { String opt = option.startsWith("-") ? option.substring(1) : option; return getName().equals(opt); } public boolean process(String option, ListIterator<String> arguments) { overviewpath = arguments.next(); return true; } } }; return new HashSet<Option>(Arrays.asList(options)); } @Override public SourceVersion getSupportedSourceVersion() { // support the latest release return SourceVersion.latest(); } }
This doclet when invoked with a command line, such as:
javadoc -doclet Example -sourcepath <source-location>will produce an output, such as:
Overview.html: overview comments ... ... CLASS: SomeKlass ..... Element (METHOD: main(java.lang.String...)) has the following comments: Entire body: The main entry point. Block tags: @param an array of Strings ...
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
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-internal+0-2016-02-27-130607.doko.src