duke@1: jjg@2112: 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: jjg@2112: 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 jjg@2112: information. From this root all other program structure jjg@2112: information can be extracted. duke@1:
-public, -protected, -package,
jjg@2112: and -private) filter program elements, producing a
duke@1: result set, called the included set, or "documented" set.
jjg@2112: (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 jjg@2112: 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)}. jjg@2112: 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: jjg@2112: {@linkplain com.sun.javadoc.Doc#isOrdinaryClass() ordinary classes}, duke@1: {@linkplain com.sun.javadoc.Doc#isEnum() enums}, jjg@2112: {@linkplain com.sun.javadoc.Doc#isError() errors} and duke@1: {@linkplain com.sun.javadoc.Doc#isException() exceptions}. jjg@2112: 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:
@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: }
jjg@2112: }
duke@1: }
duke@1:
jjg@2112: Interfaces and methods from the Javadoc API are marked in
jjg@2112: red.
jjg@2112: {@link com.sun.javadoc.Doclet Doclet} is an abstract class that specifies
jjg@2112: the invocation interface for doclets,
jjg@2112: {@link com.sun.javadoc.Doclet Doclet} holds class or interface information,
duke@1: {@link com.sun.javadoc.ExecutableMemberDoc} is a
jjg@2112: superinterface of {@link com.sun.javadoc.MethodDoc} and
jjg@2112: {@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 jjg@2112: */ jjg@2112: @jdk.Exported jjg@2112: package com.sun.javadoc;