Doclet API
DRAFT 9-internal+0-2016-08-08-112313.buildd.src
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

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 TypeNew Type
AnnotatedTypejavax.lang.model.type.Type
AnnotationDescjavax.lang.model.element.AnnotationMirror
AnnotationDesc.ElementValuePairjavax.lang.model.element.AnnotationValue
AnnotationTypeDocjavax.lang.model.element.TypeElement
AnnotationTypeElementDocjavax.lang.model.element.ExecutableElement
AnnotationValuejavax.lang.model.element.AnnotationValue
ClassDocjavax.lang.model.element.TypeElement
ConstructorDocjavax.lang.model.element.ExecutableElement
Docjavax.lang.model.element.Element
DocErrorReporterjdk.javadoc.doclet.Reporter
Docletjdk.javadoc.doclet.Doclet
ExecutableMemberDocjavax.lang.model.element.ExecutableElement
FieldDocjavax.lang.model.element.VariableElement
LanguageVersionjavax.lang.model.SourceVersion
MemberDocjavax.lang.model.element.Element
MethodDocjavax.lang.model.element.ExecutableElement
PackageDocjavax.lang.model.element.PackageElement
Parameterjavax.lang.model.element.VariableElement
ParameterizedTypejavax.lang.model.type.DeclaredType
ParamTagcom.sun.source.doctree.ParamTree
ProgramElementDocjavax.lang.model.element.Element
RootDocjdk.javadoc.doclet.DocletEnvironment
SeeTagcom.sun.source.doctree.LinkTree
com.sun.source.doctree.SeeTree
SerialFieldTagcom.sun.source.doctree.SerialFieldTree
SourcePositioncom.sun.source.util.SourcePositions
Tagcom.sun.source.doctree.DocTree
ThrowsTagcom.sun.source.doctree.ThrowsTree
Typejavax.lang.model.type.Type
TypeVariablejavax.lang.model.type.TypeVariable
WildcardTypejavax.lang.model.type.WildcardType
Since:
9
See Also:
Doclet, DocletEnvironment
Skip navigation links
Doclet API
DRAFT 9-internal+0-2016-08-08-112313.buildd.src

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-08-08-112313.buildd.src