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 javadoc comments embedded in the source.

See: Description

Interface Summary
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 Summary
Doclet.Option.Kind: The kind of an option.

## Package jdk.javadoc.doclet Description

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 javadoc comments embedded in the source.

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.

### Terminology

When calling javadoc, one can pass in package names and source file names -- these are called the specified PackageElements and TypeElements. Javadoc options are also passed in; the access control Javadoc options (`-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`.

### Example

The following is an example doclet that displays information of a class and its members, supporting an option "someoption".

     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
      ...

### 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.

Guide for mapping old types to new types
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

Since:
  9
See Also:
  `Doclet`, `DocletEnvironment`