* Note: The declarations in this package supersede those * in the older package {@code 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 {@link jdk.javadoc.doclet.Doclet} * -- the {@link jdk.javadoc.doclet.Doclet#run(DocletEnvironment) run} interface * method, defines the entry point. *
* public boolean run(DocletEnvironment environment) ** The {@link jdk.javadoc.doclet.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 {@link javax.lang.model} elements. One can further use the * APIs and utilities described by {@link javax.lang.model} to query Elements and Types. *
* * A qualified element name is one that has its package * name prepended to it, such as {@code java.lang.String}. A non-qualified * name has no package name, such as {@code 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 {@code com.sun.javadoc} API do not have equivalents in this * package. Instead, types in the {@code javax.lang.model} and {@code 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 * |