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