Doclet API
DRAFT 9-internal+0-2016-09-03-162606.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 API 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 API 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

Module, package and source file names can be provided as parameters to the javadoc tool -- these are called the specified set containing module elements, package elements and type elements.

Javadoc selection control can be specified with --show-members:value, --showtypes:value, where value can be one of the following:

The --show-package:value where a value of "exported" or "all" can be used to consider only exported packages or all packages within a module.

The --expand-requires:value, expands the "requires" directives of a module declaration, to create a module set to considered for documentation as follows:

All of the above are used to select the elements, to produce the included or the selected set.

--show-module-contents:value can be used to specify the level at module declarations could be documented, a value of "api" indicates API level documentation, and "all" indicates detailed documentation.

Interactions with older options.

The new --show-* options provide a more detailed replacement for the older options -public, -protected, -package, -private. Alternatively, the older options can continue to be used as shorter forms for combinations of the new options, as described below:
Short form options mapping
Older optionEquivalent to these values with the new option
--show-members--show-types--show-packages--show-module-contents
-publicpublicpublicexportedapi
-protectedprotectedprotectedexportedapi
-packagepackagepackageallall
-privateprivateprivateallall

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(DocletEnvironment docEnv) {
         // cache the DocTrees utility class to access DocComments
         DocTrees docTrees = docEnv.getDocTrees();

         // location of an element in the same directory as overview.html
         try {
             Element barElement = null;
             for (Element e : docEnv.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 : docEnv.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-09-03-162606.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-09-03-162606.buildd.src