+ * Note: The declarations in this package supersede those + * in the older package {@code 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 {@link jdk.javadoc.doclet.Doclet} + * -- the {@link jdk.javadoc.doclet.Doclet#run(DocletEnvironment) run} interface + * method, defines the entry point. + *
+ * public boolean run(DocletEnvironment environment) + *+ * The {@link jdk.javadoc.doclet.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 {@link javax.lang.model} elements. One can further use the + * APIs and utilities described by {@link javax.lang.model} to query Elements and Types. + *
+ + * + * A qualified element name is one that has its package + * name prepended to it, such as {@code java.lang.String}. A non-qualified + * name has no package name, such as {@code String}. + *
+ * 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 + * ... + *+ * + *
Many of the types in the old {@code com.sun.javadoc} API do not have equivalents in this + * package. Instead, types in the {@code javax.lang.model} and {@code 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. + * + *
| 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 + * |