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

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 Summary

Enum	Description
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