|
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> |