package-info.java revision 2571:10fc81ac75b4
1/* 2 * Copyright (c) 1998, 2014, 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/** 27The Doclet API (also called the Javadoc API) provides a mechanism 28for clients to inspect the source-level structure of programs and 29libraries, including javadoc comments embedded in the source. 30This is useful for documentation, program checking, automatic 31code generation and many other tools. 32<p> 33 34Doclets are invoked by javadoc and use this API to write out 35program information to files. For example, the standard doclet is called 36by default and writes out documentation to HTML files. 37<p> 38 39The invocation is defined by the abstract {@link com.sun.javadoc.Doclet} class 40-- the entry point is the {@link com.sun.javadoc.Doclet#start(RootDoc) start} method: 41<pre> 42 public static boolean <b>start</b>(RootDoc root) 43</pre> 44The {@link com.sun.javadoc.RootDoc} instance holds the root of the program structure 45information. From this root all other program structure 46information can be extracted. 47<p> 48 49<a name="terminology"></a> 50<h3>Terminology</h3> 51 52<a name="included"></a> 53When calling javadoc, you pass in package names and source file names -- 54these are called the <em>specified</em> packages and classes. 55You also pass in Javadoc options; the <em>access control</em> Javadoc options 56({@code -public}, {@code -protected}, {@code -package}, 57and {@code -private}) filter program elements, producing a 58result set, called the <em>included</em> set, or "documented" set. 59(The unfiltered set is also available through 60{@link com.sun.javadoc.PackageDoc#allClasses(boolean) allClasses(false)}.) 61<p> 62 63<a name="class"></a> 64Throughout this API, the term <em>class</em> is normally a 65shorthand for "class or interface", as in: {@link com.sun.javadoc.ClassDoc}, 66{@link com.sun.javadoc.PackageDoc#allClasses() allClasses()}, and 67{@link com.sun.javadoc.PackageDoc#findClass(String) findClass(String)}. 68In only a couple of other places, it means "class, as opposed to interface", 69as in: {@link com.sun.javadoc.Doc#isClass()}. 70In the second sense, this API calls out four kinds of classes: 71{@linkplain com.sun.javadoc.Doc#isOrdinaryClass() ordinary classes}, 72{@linkplain com.sun.javadoc.Doc#isEnum() enums}, 73{@linkplain com.sun.javadoc.Doc#isError() errors} and 74{@linkplain com.sun.javadoc.Doc#isException() exceptions}. 75Throughout the API, the detailed description of each program element 76describes explicitly which meaning is being used. 77<p> 78 79<a name="qualified"></a> 80A <em>qualified</em> class or interface name is one that has its package 81name prepended to it, such as {@code java.lang.String}. A non-qualified 82name has no package name, such as {@code String}. 83<p> 84 85<a name="example"></a> 86<h3>Example</h3> 87 88The following is an example doclet that 89displays information in the {@code @param} tags of the processed 90classes: 91<pre> 92import com.sun.javadoc.*; 93 94public class ListParams extends <span style="color:red" >Doclet</span> { 95 96 public static boolean start(<span style="color:red" >RootDoc</span> root) { 97 <span style="color:red" >ClassDoc</span>[] classes = root.<span style="color:red" >classes</span>(); 98 for (int i = 0; i < classes.length; ++i) { 99 <span style="color:red" >ClassDoc</span> cd = classes[i]; 100 printMembers(cd.<span style="color:red" >constructors</span>()); 101 printMembers(cd.<span style="color:red" >methods</span>()); 102 } 103 return true; 104 } 105 106 static void printMembers(<span style="color:red" >ExecutableMemberDoc</span>[] mems) { 107 for (int i = 0; i < mems.length; ++i) { 108 <span style="color:red" >ParamTag</span>[] params = mems[i].<span style="color:red" >paramTags</span>(); 109 System.out.println(mems[i].<span style="color:red" >qualifiedName</span>()); 110 for (int j = 0; j < params.length; ++j) { 111 System.out.println(" " + params[j].<span style="color:red" >parameterName</span>() 112 + " - " + params[j].<span style="color:red" >parameterComment</span>()); 113 } 114 } 115 } 116} 117</pre> 118Interfaces and methods from the Javadoc API are marked in 119<span style="color:red" >red</span>. 120{@link com.sun.javadoc.Doclet Doclet} is an abstract class that specifies 121the invocation interface for doclets, 122{@link com.sun.javadoc.Doclet Doclet} holds class or interface information, 123{@link com.sun.javadoc.ExecutableMemberDoc} is a 124superinterface of {@link com.sun.javadoc.MethodDoc} and 125{@link com.sun.javadoc.ConstructorDoc}, 126and {@link com.sun.javadoc.ParamTag} holds information 127from "{@code @param}" tags. 128<p> 129This doclet when invoked with a command line like: 130<pre> 131 javadoc -doclet ListParams -sourcepath <source-location> java.util 132</pre> 133producing output like: 134<pre> 135 ... 136 java.util.ArrayList.add 137 index - index at which the specified element is to be inserted. 138 element - element to be inserted. 139 java.util.ArrayList.remove 140 index - the index of the element to removed. 141 ... 142 143</pre> 144@see com.sun.javadoc.Doclet 145@see com.sun.javadoc.RootDoc 146*/ 147@jdk.Exported 148package com.sun.javadoc; 149