Doclet API Package

duke@1: duke@1: duke@1: Doclet API Package duke@1: duke@1: duke@1: duke@1: duke@1: The Doclet API (also called the Javadoc API) provides a mechanism duke@1: for clients to inspect the source-level structure of programs and duke@1: libraries, including javadoc comments embedded in the source. duke@1: This is useful for documentation, program checking, automatic duke@1: code generation and many other tools. duke@1:

duke@1: duke@1: Doclets are invoked by javadoc and use this API to write out duke@1: program information to files. For example, the standard doclet is called duke@1: by default and writes out documentation to HTML files. duke@1:

duke@1: duke@1: The invocation is defined by the abstract {@link com.sun.javadoc.Doclet} class duke@1: -- the entry point is the {@link com.sun.javadoc.Doclet#start(RootDoc) start} method: duke@1:

duke@1:     public static boolean start(RootDoc root)
duke@1:

duke@1: The {@link com.sun.javadoc.RootDoc} instance holds the root of the program structure duke@1: information. From this root all other program structure duke@1: information can be extracted. duke@1:

duke@1: duke@1: duke@1:

Terminology

duke@1: duke@1: duke@1: When calling javadoc, you pass in package names and source file names -- duke@1: these are called the specified packages and classes. duke@1: You also pass in Javadoc options; the access control Javadoc options duke@1: (-public, -protected, -package, duke@1: and -private) filter program elements, producing a duke@1: result set, called the included set, or "documented" set. duke@1: (The unfiltered set is also available through duke@1: {@link com.sun.javadoc.PackageDoc#allClasses(boolean) allClasses(false)}.) duke@1:

duke@1: duke@1: duke@1: Throughout this API, the term class is normally a duke@1: shorthand for "class or interface", as in: {@link com.sun.javadoc.ClassDoc}, duke@1: {@link com.sun.javadoc.PackageDoc#allClasses() allClasses()}, and duke@1: {@link com.sun.javadoc.PackageDoc#findClass(String) findClass(String)}. duke@1: In only a couple of other places, it means "class, as opposed to interface", duke@1: as in: {@link com.sun.javadoc.Doc#isClass()}. duke@1: In the second sense, this API calls out four kinds of classes: duke@1: {@linkplain com.sun.javadoc.Doc#isOrdinaryClass() ordinary classes}, duke@1: {@linkplain com.sun.javadoc.Doc#isEnum() enums}, duke@1: {@linkplain com.sun.javadoc.Doc#isError() errors} and duke@1: {@linkplain com.sun.javadoc.Doc#isException() exceptions}. duke@1: Throughout the API, the detailed description of each program element duke@1: describes explicitly which meaning is being used. duke@1:

duke@1: duke@1: duke@1: A qualified class or interface name is one that has its package duke@1: name prepended to it, such as java.lang.String. A non-qualified duke@1: name has no package name, such as String. duke@1:

duke@1: duke@1: duke@1:

Example

duke@1: duke@1: The following is an example doclet that duke@1: displays information in the @param tags of the processed duke@1: classes: duke@1:

duke@1: import com.sun.javadoc.*;
duke@1: 
duke@1: public class ListParams extends Doclet {
duke@1: 
duke@1:     public static boolean start(RootDoc root) {
duke@1:         ClassDoc[] classes = root.classes();
duke@1:         for (int i = 0; i < classes.length; ++i) {
duke@1:             ClassDoc cd = classes[i];
duke@1:             printMembers(cd.constructors());
duke@1:             printMembers(cd.methods());
duke@1:         }
duke@1:         return true;
duke@1:     }
duke@1: 
duke@1:     static void printMembers(ExecutableMemberDoc[] mems) {
duke@1:         for (int i = 0; i < mems.length; ++i) {
duke@1:             ParamTag[] params = mems[i].paramTags();
duke@1:             System.out.println(mems[i].qualifiedName());
duke@1:             for (int j = 0; j < params.length; ++j) {
duke@1:                 System.out.println("   " + params[j].parameterName()
duke@1:                     + " - " + params[j].parameterComment());
duke@1:             }
duke@1:         }
duke@1:     }        
duke@1: }
duke@1:

duke@1: Interfaces and methods from the Javadoc API are marked in duke@1: red. duke@1: {@link com.sun.javadoc.Doclet Doclet} is an abstract class that specifies duke@1: the invocation interface for doclets, duke@1: {@link com.sun.javadoc.Doclet Doclet} holds class or interface information, duke@1: {@link com.sun.javadoc.ExecutableMemberDoc} is a duke@1: superinterface of {@link com.sun.javadoc.MethodDoc} and duke@1: {@link com.sun.javadoc.ConstructorDoc}, duke@1: and {@link com.sun.javadoc.ParamTag} holds information duke@1: from "@param" tags. duke@1:

duke@1: This doclet when invoked with a command line like: duke@1:

duke@1:     javadoc -doclet ListParams -sourcepath <source-location> java.util
duke@1:

duke@1: producing output like: duke@1:

duke@1:     ...
duke@1:     java.util.ArrayList.add
duke@1:        index - index at which the specified element is to be inserted.
duke@1:        element - element to be inserted.
duke@1:     java.util.ArrayList.remove
duke@1:        index - the index of the element to removed.
duke@1:     ...
duke@1: 
duke@1:

duke@1: @see com.sun.javadoc.Doclet duke@1: @see com.sun.javadoc.RootDoc duke@1: duke@1: