Mercurial > jdk8-mips64-public > langtools / file comparison
comparison: src/share/classes/com/sun/javadoc/package.html
src/share/classes/com/sun/javadoc/package.html
- changeset 1
- 9a66ca7c79fa
- child 554
- 9d9f26857129
equal
deleted
inserted
replaced
| -1:000000000000 | 1:9a66ca7c79fa |
|---|---|
| 1 <html> | |
| 2 <head> | |
| 3 <TITLE>Doclet API Package</TITLE> | |
| 4 <!-- | |
| 5 | |
| 6 Copyright 1998-2003 Sun Microsystems, Inc. All Rights Reserved. | |
| 7 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
| 8 | |
| 9 This code is free software; you can redistribute it and/or modify it | |
| 10 under the terms of the GNU General Public License version 2 only, as | |
| 11 published by the Free Software Foundation. Sun designates this | |
| 12 particular file as subject to the "Classpath" exception as provided | |
| 13 by Sun in the LICENSE file that accompanied this code. | |
| 14 | |
| 15 This code is distributed in the hope that it will be useful, but WITHOUT | |
| 16 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| 17 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| 18 version 2 for more details (a copy is included in the LICENSE file that | |
| 19 accompanied this code). | |
| 20 | |
| 21 You should have received a copy of the GNU General Public License version | |
| 22 2 along with this work; if not, write to the Free Software Foundation, | |
| 23 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
| 24 | |
| 25 Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, | |
| 26 CA 95054 USA or visit www.sun.com if you need additional information or | |
| 27 have any questions. | |
| 28 --> | |
| 29 </head> | |
| 30 <body bgcolor="white"> | |
| 31 | |
| 32 The Doclet API (also called the Javadoc API) provides a mechanism | |
| 33 for clients to inspect the source-level structure of programs and | |
| 34 libraries, including javadoc comments embedded in the source. | |
| 35 This is useful for documentation, program checking, automatic | |
| 36 code generation and many other tools. | |
| 37 <p> | |
| 38 | |
| 39 Doclets are invoked by javadoc and use this API to write out | |
| 40 program information to files. For example, the standard doclet is called | |
| 41 by default and writes out documentation to HTML files. | |
| 42 <p> | |
| 43 | |
| 44 The invocation is defined by the abstract {@link com.sun.javadoc.Doclet} class | |
| 45 -- the entry point is the {@link com.sun.javadoc.Doclet#start(RootDoc) start} method: | |
| 46 <pre> | |
| 47 public static boolean <b>start</b>(RootDoc root) | |
| 48 </pre> | |
| 49 The {@link com.sun.javadoc.RootDoc} instance holds the root of the program structure | |
| 50 information. From this root all other program structure | |
| 51 information can be extracted. | |
| 52 <p> | |
| 53 | |
| 54 <a name="terminology"></a> | |
| 55 <h3>Terminology</h3> | |
| 56 | |
| 57 <a name="included"></a> | |
| 58 When calling javadoc, you pass in package names and source file names -- | |
| 59 these are called the <em>specified</em> packages and classes. | |
| 60 You also pass in Javadoc options; the <em>access control</em> Javadoc options | |
| 61 (<code>-public</code>, <code>-protected</code>, <code>-package</code>, | |
| 62 and <code>-private</code>) filter program elements, producing a | |
| 63 result set, called the <em>included</em> set, or "documented" set. | |
| 64 (The unfiltered set is also available through | |
| 65 {@link com.sun.javadoc.PackageDoc#allClasses(boolean) allClasses(false)}.) | |
| 66 <p> | |
| 67 | |
| 68 <a name="class"></a> | |
| 69 Throughout this API, the term <em>class</em> is normally a | |
| 70 shorthand for "class or interface", as in: {@link com.sun.javadoc.ClassDoc}, | |
| 71 {@link com.sun.javadoc.PackageDoc#allClasses() allClasses()}, and | |
| 72 {@link com.sun.javadoc.PackageDoc#findClass(String) findClass(String)}. | |
| 73 In only a couple of other places, it means "class, as opposed to interface", | |
| 74 as in: {@link com.sun.javadoc.Doc#isClass()}. | |
| 75 In the second sense, this API calls out four kinds of classes: | |
| 76 {@linkplain com.sun.javadoc.Doc#isOrdinaryClass() ordinary classes}, | |
| 77 {@linkplain com.sun.javadoc.Doc#isEnum() enums}, | |
| 78 {@linkplain com.sun.javadoc.Doc#isError() errors} and | |
| 79 {@linkplain com.sun.javadoc.Doc#isException() exceptions}. | |
| 80 Throughout the API, the detailed description of each program element | |
| 81 describes explicitly which meaning is being used. | |
| 82 <p> | |
| 83 | |
| 84 <a name="qualified"></a> | |
| 85 A <em>qualified</em> class or interface name is one that has its package | |
| 86 name prepended to it, such as <code>java.lang.String</code>. A non-qualified | |
| 87 name has no package name, such as <code>String</code>. | |
| 88 <p> | |
| 89 | |
| 90 <a name="example"></a> | |
| 91 <h3>Example</h3> | |
| 92 | |
| 93 The following is an example doclet that | |
| 94 displays information in the <code>@param</code> tags of the processed | |
| 95 classes: | |
| 96 <pre> | |
| 97 import com.sun.javadoc.*; | |
| 98 | |
| 99 public class ListParams extends <font color=red title="Doclet API">Doclet</font> { | |
| 100 | |
| 101 public static boolean start(<font color=red title="Doclet API">RootDoc</font> root) { | |
| 102 <font color=red title="Doclet API">ClassDoc</font>[] classes = root.<font color=red title="Doclet API">classes</font>(); | |
| 103 for (int i = 0; i < classes.length; ++i) { | |
| 104 <font color=red title="Doclet API">ClassDoc</font> cd = classes[i]; | |
| 105 printMembers(cd.<font color=red title="Doclet API">constructors</font>()); | |
| 106 printMembers(cd.<font color=red title="Doclet API">methods</font>()); | |
| 107 } | |
| 108 return true; | |
| 109 } | |
| 110 | |
| 111 static void printMembers(<font color=red title="Doclet API">ExecutableMemberDoc</font>[] mems) { | |
| 112 for (int i = 0; i < mems.length; ++i) { | |
| 113 <font color=red title="Doclet API">ParamTag</font>[] params = mems[i].<font color=red title="Doclet API">paramTags</font>(); | |
| 114 System.out.println(mems[i].<font color=red title="Doclet API">qualifiedName</font>()); | |
| 115 for (int j = 0; j < params.length; ++j) { | |
| 116 System.out.println(" " + params[j].<font color=red title="Doclet API">parameterName</font>() | |
| 117 + " - " + params[j].<font color=red title="Doclet API">parameterComment</font>()); | |
| 118 } | |
| 119 } | |
| 120 } | |
| 121 } | |
| 122 </pre> | |
| 123 Interfaces and methods from the Javadoc API are marked in | |
| 124 <font color=red title="Doclet API">red</font>. | |
| 125 {@link com.sun.javadoc.Doclet Doclet} is an abstract class that specifies | |
| 126 the invocation interface for doclets, | |
| 127 {@link com.sun.javadoc.Doclet Doclet} holds class or interface information, | |
| 128 {@link com.sun.javadoc.ExecutableMemberDoc} is a | |
| 129 superinterface of {@link com.sun.javadoc.MethodDoc} and | |
| 130 {@link com.sun.javadoc.ConstructorDoc}, | |
| 131 and {@link com.sun.javadoc.ParamTag} holds information | |
| 132 from "<code>@param</code>" tags. | |
| 133 <p> | |
| 134 This doclet when invoked with a command line like: | |
| 135 <pre> | |
| 136 javadoc -doclet ListParams -sourcepath <source-location> java.util | |
| 137 </pre> | |
| 138 producing output like: | |
| 139 <pre> | |
| 140 ... | |
| 141 java.util.ArrayList.add | |
| 142 index - index at which the specified element is to be inserted. | |
| 143 element - element to be inserted. | |
| 144 java.util.ArrayList.remove | |
| 145 index - the index of the element to removed. | |
| 146 ... | |
| 147 | |
| 148 </pre> | |
| 149 @see com.sun.javadoc.Doclet | |
| 150 @see com.sun.javadoc.RootDoc | |
| 151 </BODY> | |
| 152 </HTML> |
