package-info.java revision 3233:b5d08bc0d224
1/* 2 * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26/** 27 * The Doclet API provides an environment which, in conjunction with 28 * the Language Model API and Compiler Tree API, allows clients 29 * to inspect the source-level structures of programs and 30 * libraries, including javadoc comments embedded in the source. 31 * 32 * <p style="font-style: italic"> 33 * <b>Note:</b> The declarations in this package supersede those 34 * in the older package {@code com.sun.javadoc}. For details on the 35 * mapping of old types to new types, see the 36 * <a href="#migration">Migration Guide</a>. 37 * </p> 38 * 39 * <p> 40 * Doclets are invoked by javadoc and this API can be used to write out 41 * program information to files. For example, the standard doclet is 42 * invoked by default, to generate HTML documentation. 43 * <p> 44 45 * The invocation is defined by the interface {@link jdk.javadoc.doclet.Doclet} 46 * -- the {@link jdk.javadoc.doclet.Doclet#run(DocletEnvironment) run} interface 47 * method, defines the entry point. 48 * <pre> 49 * public boolean <b>run</b>(DocletEnvironment environment) 50 * </pre> 51 * The {@link jdk.javadoc.doclet.DocletEnvironment} instance holds the environment that the 52 * doclet will be initialized with. From this environment all other information can be 53 * extracted, in the form of {@link javax.lang.model} elements. One can further use the 54 * APIs and utilities described by {@link javax.lang.model} to query Elements and Types. 55 * <p> 56 * 57 * <a name="terminology"></a> 58 * <h3>Terminology</h3> 59 * 60 * <a name="included"></a> 61 * When calling javadoc, one can pass in package names and source file names -- 62 * these are called the <em>specified</em> PackageElements and TypeElements. 63 * Javadoc options are also passed in; the <em>access control</em> Javadoc options 64 * ({@code -public}, {@code -protected}, {@code -package}, 65 * and {@code -private}) are used to filter program elements, producing a 66 * result set, called the <em>included</em> set, or "selected" set. 67 * <p> 68 69 * <a name="qualified"></a> 70 * A <em>qualified</em> element name is one that has its package 71 * name prepended to it, such as {@code java.lang.String}. A non-qualified 72 * name has no package name, such as {@code String}. 73 * <p> 74 * 75 * <a name="example"></a> 76 * <h3>Example</h3> 77 * 78 * The following is an example doclet that displays information of a class 79 * and its members, supporting an option "someoption". 80 * <pre> 81 * import com.sun.source.doctree.DocCommentTree; 82 * import com.sun.source.util.DocTrees; 83 * import java.io.IOException; 84 * import java.util.Collections; 85 * import java.util.Set; 86 * import javax.lang.model.SourceVersion; 87 * import javax.lang.model.element.Element; 88 * import javax.lang.model.element.TypeElement; 89 * import jdk.javadoc.doclet.*; 90 * 91 * public class Example implements Doclet { 92 * 93 * @Override 94 * public void init(Locale locale, Reporter reporter) { 95 * return; 96 * } 97 * 98 * @Override 99 * public boolean run(RootDoc root) { 100 * // cache the DocTrees utility class to access DocComments 101 * DocTrees docTrees = root.getDocTrees(); 102 * 103 * // location of an element in the same directory as overview.html 104 * try { 105 * Element barElement = null; 106 * for (Element e : root.getIncludedClasses()) { 107 * if (e.getSimpleName().toString().equals("FooBar")) { 108 * barElement = e; 109 * } 110 * } 111 * DocCommentTree docCommentTree = 112 * docTrees.getDocCommentTree(barElement, "overview.html"); 113 * if (docCommentTree != null) { 114 * System.out.println("Overview html: " + 115 * docCommentTree.getFullBody()); 116 * } 117 * } catch (IOException missing) { 118 * System.err.println("No overview.html found."); 119 * } 120 * 121 * for (TypeElement t : root.getIncludedClasses()) { 122 * System.out.println(t.getKind() + ":" + t); 123 * for (Element e : t.getEnclosedElements()) { 124 * DocCommentTree docCommentTree = docTrees.getDocCommentTree(e); 125 * if (docCommentTree != null) { 126 * System.out.println("Element (" + e.getKind() + ": " + 127 * e + ") has the following comments:"); 128 * System.out.println("Entire body: " + docCommentTree.getFullBody()); 129 * System.out.println("Block tags: " + docCommentTree.getBlockTags()); 130 * } else { 131 * System.out.println("no comment."); 132 * } 133 * } 134 * } 135 * return true; 136 * } 137 * 138 * @Override 139 * public String getName() { 140 * return "Example"; 141 * } 142 * 143 * private String someOption; 144 * 145 * @Override 146 * public Set<Option> getSupportedOptions() { 147 * Option[] options = { 148 * new Option() { 149 * public int getArgumentCount() { 150 * return 1; 151 * } 152 * public String getDescription() { 153 * return "someoption"; 154 * } 155 * public Option.Kind getKind() { 156 * return Option.Kind.STANDARD; 157 * } 158 * public String getName() { 159 * return "someoption"; 160 * } 161 * public String getParameters() { 162 * return "url"; 163 * } 164 * public boolean matches(String option) { 165 * String opt = option.startsWith("-") ? option.substring(1) : option; 166 * return getName().equals(opt); 167 * } 168 * public boolean process(String option, ListIterator<String> arguments) { 169 * overviewpath = arguments.next(); 170 * return true; 171 * } 172 * } 173 * }; 174 * return new HashSet<Option>(Arrays.asList(options)); 175 * } 176 * 177 * @Override 178 * public SourceVersion getSupportedSourceVersion() { 179 * // support the latest release 180 * return SourceVersion.latest(); 181 * } 182 * } 183 * </pre> 184 * <p> 185 * This doclet when invoked with a command line, such as: 186 * <pre> 187 * javadoc -doclet Example -sourcepath <source-location> 188 * </pre> 189 * will produce an output, such as: 190 * <pre> 191 * Overview.html: overview comments 192 * ... 193 * ... 194 * CLASS: SomeKlass 195 * ..... 196 * Element (METHOD: main(java.lang.String...)) has the following comments: 197 * Entire body: The main entry point. 198 * Block tags: @param an array of Strings 199 * ... 200 * </pre> 201 * 202 * <h3><a name="migration">Migration Guide</a></h3> 203 * 204 * <p>Many of the types in the old {@code com.sun.javadoc} API do not have equivalents in this 205 * package. Instead, types in the {@code javax.lang.model} and {@code com.sun.source} APIs 206 * are used instead. 207 * 208 * <p>The following table gives a guide to the mapping from old types to their replacements. 209 * In some cases, there is no direct equivalent. 210 * 211 * <table style="font-family: monospace" border=1> 212 <caption>Guide for mapping old types to new types</caption> 213 <tr><th>Old Type<th>New Type 214 <tr><td>AnnotatedType<td>javax.lang.model.type.Type 215 <tr><td>AnnotationDesc<td>javax.lang.model.element.AnnotationMirror 216 <tr><td>AnnotationDesc.ElementValuePair<td>javax.lang.model.element.AnnotationValue 217 <tr><td>AnnotationTypeDoc<td>javax.lang.model.element.TypeElement 218 <tr><td>AnnotationTypeElementDoc<td>javax.lang.model.element.ExecutableElement 219 <tr><td>AnnotationValue<td>javax.lang.model.element.AnnotationValue 220 <tr><td>ClassDoc<td>javax.lang.model.element.TypeElement 221 <tr><td>ConstructorDoc<td>javax.lang.model.element.ExecutableElement 222 <tr><td>Doc<td>javax.lang.model.element.Element 223 <tr><td>DocErrorReporter<td>jdk.javadoc.doclet.Reporter 224 <tr><td>Doclet<td>jdk.javadoc.doclet.Doclet 225 <tr><td>ExecutableMemberDoc<td>javax.lang.model.element.ExecutableElement 226 <tr><td>FieldDoc<td>javax.lang.model.element.VariableElement 227 <tr><td>LanguageVersion<td>javax.lang.model.SourceVersion 228 <tr><td>MemberDoc<td>javax.lang.model.element.Element 229 <tr><td>MethodDoc<td>javax.lang.model.element.ExecutableElement 230 <tr><td>PackageDoc<td>javax.lang.model.element.PackageElement 231 <tr><td>Parameter<td>javax.lang.model.element.VariableElement 232 <tr><td>ParameterizedType<td>javax.lang.model.type.DeclaredType 233 <tr><td>ParamTag<td>com.sun.source.doctree.ParamTree 234 <tr><td>ProgramElementDoc<td>javax.lang.model.element.Element 235 <tr><td>RootDoc<td>jdk.javadoc.doclet.DocletEnvironment 236 <tr><td>SeeTag<td>com.sun.source.doctree.LinkTree<br>com.sun.source.doctree.SeeTree 237 <tr><td>SerialFieldTag<td>com.sun.source.doctree.SerialFieldTree 238 <tr><td>SourcePosition<td>com.sun.source.util.SourcePositions 239 <tr><td>Tag<td>com.sun.source.doctree.DocTree 240 <tr><td>ThrowsTag<td>com.sun.source.doctree.ThrowsTree 241 <tr><td>Type<td>javax.lang.model.type.Type 242 <tr><td>TypeVariable<td>javax.lang.model.type.TypeVariable 243 <tr><td>WildcardType<td>javax.lang.model.type.WildcardType 244 * </table> 245 * 246 * @see jdk.javadoc.doclet.Doclet 247 * @see jdk.javadoc.doclet.DocletEnvironment 248 * @since 9 249*/ 250 251package jdk.javadoc.doclet; 252