package-info.java revision 3793:5a2b9f22ba5d
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 API 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 52 * environment that the doclet will be initialized with. From this environment 53 * all other information can be extracted, in the form of 54 * {@link javax.lang.model.element.Element elements}. One can further use the APIs and utilities 55 * described by {@link javax.lang.model Language Model API} to query Elements and Types. 56 * <p> 57 * 58 * <a name="terminology"></a> 59 * <h3>Terminology</h3> 60 * 61 * <dl> 62 * <dt><a name="selected"></a>Selected</dt> 63 * <dd>An element is considered to be <em>selected</em>, if the 64 * <em>selection controls</em> <a href="#options">allow</a> it 65 * to be documented. (Note that synthetic elements are never 66 * selected.) 67 * </dd> 68 * 69 * <dt><a name="specified"></a>Specified</dt> 70 * <dd>The set of elements specified by the user are considered to be <em>specified 71 * elements</em>. Specified elements provide the starting points 72 * for determining the <em>included elements</em> to be documented. 73 * </dd> 74 * 75 * <dt><a name="included"></a>Included</dt> 76 * <dd>An element is considered to be <em>included</em>, if it is 77 * <em>specified</em> if it contains a <em>specified</em> element, 78 * or it is enclosed in a <em>specified</em> element, and is <em>selected</em>. 79 * Included elements will be documented. 80 * </dd> 81 * 82 * </dl> 83 * <p> 84 * <a name="options"></a> 85 * <h3>Options</h3> 86 * Javadoc <em>selection control</em> can be specified with these options 87 * as follows: 88 * <ul> 89 * <li>{@code --show-members:value} and {@code --show-types:value} can 90 * be used to filter the members, with the following values: 91 * <ul> 92 * <li> public -- considers only public elements 93 * <li> protected -- considers public and protected elements 94 * <li> package -- considers public, protected and package private elements 95 * <li> private -- considers all elements 96 * </ul> 97 * 98 * <li>{@code --show-packages:value} "exported" or "all" can be used 99 * to consider only exported packages or all packages within a module. 100 * 101 * <li>{@code --show-module-contents:value} can be used to specify the level at 102 * module declarations could be documented. A value of "api" indicates API 103 * level documentation, and "all" indicates detailed documentation. 104 * </ul> 105 * The following options can be used to specify the elements to be documented: 106 * <ul> 107 * <li>{@code --module} documents the specified modules. 108 * 109 * <li>{@code --expand-requires:value} expand the set of modules to be documented 110 * by including some or all of the modules dependencies. The value may be 111 * one of: 112 * <ul> 113 * <li> transitive -- each module specified explicitly on the command line is 114 * expanded to include the closure of its transitive dependencies 115 * <li> all -- each module specified explicitly on the command line 116 * is expanded to include the closure of its transitive dependencies, 117 * and also all of its direct dependencies 118 * </ul> 119 * By default, only the specified modules will be considered, without expansion 120 * of the module dependencies. 121 * 122 * <li>{@code packagenames} can be used to specify packages. 123 * <li>{@code -subpackages} can be used to recursively load packages. 124 * <li>{@code -exclude} can be used exclude package directories. 125 * <li>{@code sourcefilenames} can be used to specify source file names. 126 * </ul> 127 * <p> 128 * <a name="legacy-interactions"></a> 129 * <h4>Interactions with older options.</h4> 130 * 131 * The new {@code --show-*} options provide a more detailed replacement 132 * for the older options -public, -protected, -package, -private. 133 * Alternatively, the older options can continue to be used as shorter 134 * forms for combinations of the new options, as described below: 135 <table style="font-family: monospace" border=1> 136 <caption>Short form options mapping</caption> 137 <tr><th>Older option<th colspan="5">Equivalent to these values with the new option 138 <tr><th><th>{@code --show-members}<th>{@code --show-types}<th>{@code --show-packages}<th>{@code --show-module-contents} 139 <tr><td>{@code -public}<td>public<td>public<td>exported<td>api 140 <tr><td>{@code -protected}<td>protected<td>protected<td>exported<td>api 141 <tr><td>{@code -package}<td>package<td>package<td>all<td>all 142 <tr><td>{@code -private}<td>private<td>private<td>all<td>all 143 </table> 144 * <p> 145 * <a name="qualified"></a> 146 * A <em>qualified</em> element name is one that has its package 147 * name prepended to it, such as {@code java.lang.String}. A non-qualified 148 * name has no package name, such as {@code String}. 149 * <p> 150 * 151 * <a name="example"></a> 152 * <h3>Example</h3> 153 * 154 * The following is an example doclet that displays information of a class 155 * and its members, supporting an option. 156 * <pre> 157 * // note imports deleted for clarity 158 * public class Example implements Doclet { 159 * Reporter reporter; 160 * @Override 161 * public void init(Locale locale, Reporter reporter) { 162 * reporter.print(Kind.NOTE, "Doclet using locale: " + locale); 163 * this.reporter = reporter; 164 * } 165 * 166 * public void printElement(DocTrees trees, Element e) { 167 * DocCommentTree docCommentTree = trees.getDocCommentTree(e); 168 * if (docCommentTree != null) { 169 * System.out.println("Element (" + e.getKind() + ": " 170 * + e + ") has the following comments:"); 171 * System.out.println("Entire body: " + docCommentTree.getFullBody()); 172 * System.out.println("Block tags: " + docCommentTree.getBlockTags()); 173 * } 174 * } 175 * 176 * @Override 177 * public boolean run(DocletEnvironment docEnv) { 178 * reporter.print(Kind.NOTE, "overviewfile: " + overviewfile); 179 * // get the DocTrees utility class to access document comments 180 * DocTrees docTrees = docEnv.getDocTrees(); 181 * 182 * // location of an element in the same directory as overview.html 183 * try { 184 * Element e = ElementFilter.typesIn(docEnv.getSpecifiedElements()).iterator().next(); 185 * DocCommentTree docCommentTree 186 * = docTrees.getDocCommentTree(e, overviewfile); 187 * if (docCommentTree != null) { 188 * System.out.println("Overview html: " + docCommentTree.getFullBody()); 189 * } 190 * } catch (IOException missing) { 191 * reporter.print(Kind.ERROR, "No overview.html found."); 192 * } 193 * 194 * for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) { 195 * System.out.println(t.getKind() + ":" + t); 196 * for (Element e : t.getEnclosedElements()) { 197 * printElement(docTrees, e); 198 * } 199 * } 200 * return true; 201 * } 202 * 203 * @Override 204 * public String getName() { 205 * return "Example"; 206 * } 207 * 208 * private String overviewfile; 209 * 210 * @Override 211 * public Set<? extends Option> getSupportedOptions() { 212 * Option[] options = { 213 * new Option() { 214 * private final List<String> someOption = Arrays.asList( 215 * "-overviewfile", 216 * "--overview-file", 217 * "-o" 218 * ); 219 * 220 * @Override 221 * public int getArgumentCount() { 222 * return 1; 223 * } 224 * 225 * @Override 226 * public String getDescription() { 227 * return "an option with aliases"; 228 * } 229 * 230 * @Override 231 * public Option.Kind getKind() { 232 * return Option.Kind.STANDARD; 233 * } 234 * 235 * @Override 236 * public List<String> getNames() { 237 * return someOption; 238 * } 239 * 240 * @Override 241 * public String getParameters() { 242 * return "file"; 243 * } 244 * 245 * @Override 246 * public boolean process(String opt, List<String> arguments) { 247 * overviewfile = arguments.get(0); 248 * return true; 249 * } 250 * } 251 * }; 252 * return new HashSet<>(Arrays.asList(options)); 253 * } 254 * 255 * @Override 256 * public SourceVersion getSupportedSourceVersion() { 257 * // support the latest release 258 * return SourceVersion.latest(); 259 * } 260 * } 261 * </pre> 262 * <p> 263 * This doclet can be invoked with a command line, such as: 264 * <pre> 265 * javadoc -doclet Example \ 266 * -overviewfile overview.html \ 267 * -sourcepath source-location \ 268 * source-location/Example.java 269 * </pre> 270 * 271 * <h3><a name="migration">Migration Guide</a></h3> 272 * 273 * <p>Many of the types in the old {@code com.sun.javadoc} API do not have equivalents in this 274 * package. Instead, types in the {@code javax.lang.model} and {@code com.sun.source} APIs 275 * are used instead. 276 * 277 * <p>The following table gives a guide to the mapping from old types to their replacements. 278 * In some cases, there is no direct equivalent. 279 * 280 * <table style="font-family: monospace" border=1> 281 <caption>Guide for mapping old types to new types</caption> 282 <tr><th>Old Type<th>New Type 283 <tr><td>AnnotatedType<td>javax.lang.model.type.Type 284 <tr><td>AnnotationDesc<td>javax.lang.model.element.AnnotationMirror 285 <tr><td>AnnotationDesc.ElementValuePair<td>javax.lang.model.element.AnnotationValue 286 <tr><td>AnnotationTypeDoc<td>javax.lang.model.element.TypeElement 287 <tr><td>AnnotationTypeElementDoc<td>javax.lang.model.element.ExecutableElement 288 <tr><td>AnnotationValue<td>javax.lang.model.element.AnnotationValue 289 <tr><td>ClassDoc<td>javax.lang.model.element.TypeElement 290 <tr><td>ConstructorDoc<td>javax.lang.model.element.ExecutableElement 291 <tr><td>Doc<td>javax.lang.model.element.Element 292 <tr><td>DocErrorReporter<td>jdk.javadoc.doclet.Reporter 293 <tr><td>Doclet<td>jdk.javadoc.doclet.Doclet 294 <tr><td>ExecutableMemberDoc<td>javax.lang.model.element.ExecutableElement 295 <tr><td>FieldDoc<td>javax.lang.model.element.VariableElement 296 <tr><td>LanguageVersion<td>javax.lang.model.SourceVersion 297 <tr><td>MemberDoc<td>javax.lang.model.element.Element 298 <tr><td>MethodDoc<td>javax.lang.model.element.ExecutableElement 299 <tr><td>PackageDoc<td>javax.lang.model.element.PackageElement 300 <tr><td>Parameter<td>javax.lang.model.element.VariableElement 301 <tr><td>ParameterizedType<td>javax.lang.model.type.DeclaredType 302 <tr><td>ParamTag<td>com.sun.source.doctree.ParamTree 303 <tr><td>ProgramElementDoc<td>javax.lang.model.element.Element 304 <tr><td>RootDoc<td>jdk.javadoc.doclet.DocletEnvironment 305 <tr><td>SeeTag<td>com.sun.source.doctree.LinkTree<br>com.sun.source.doctree.SeeTree 306 <tr><td>SerialFieldTag<td>com.sun.source.doctree.SerialFieldTree 307 <tr><td>SourcePosition<td>com.sun.source.util.SourcePositions 308 <tr><td>Tag<td>com.sun.source.doctree.DocTree 309 <tr><td>ThrowsTag<td>com.sun.source.doctree.ThrowsTree 310 <tr><td>Type<td>javax.lang.model.type.Type 311 <tr><td>TypeVariable<td>javax.lang.model.type.TypeVariable 312 <tr><td>WildcardType<td>javax.lang.model.type.WildcardType 313 * </table> 314 * 315 * @see jdk.javadoc.doclet.Doclet 316 * @see jdk.javadoc.doclet.DocletEnvironment 317 * @since 9 318*/ 319 320package jdk.javadoc.doclet; 321