|
1 /* |
|
2 * Copyright (c) 1998, 2013, 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 (also called the Javadoc API) provides a mechanism |
|
28 for clients to inspect the source-level structure of programs and |
|
29 libraries, including javadoc comments embedded in the source. |
|
30 This is useful for documentation, program checking, automatic |
|
31 code generation and many other tools. |
|
32 <p> |
|
33 |
|
34 Doclets are invoked by javadoc and use this API to write out |
|
35 program information to files. For example, the standard doclet is called |
|
36 by default and writes out documentation to HTML files. |
|
37 <p> |
|
38 |
|
39 The 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> |
|
44 The {@link com.sun.javadoc.RootDoc} instance holds the root of the program structure |
|
45 information. From this root all other program structure |
|
46 information can be extracted. |
|
47 <p> |
|
48 |
|
49 <a name="terminology"></a> |
|
50 <h3>Terminology</h3> |
|
51 |
|
52 <a name="included"></a> |
|
53 When calling javadoc, you pass in package names and source file names -- |
|
54 these are called the <em>specified</em> packages and classes. |
|
55 You also pass in Javadoc options; the <em>access control</em> Javadoc options |
|
56 (<code>-public</code>, <code>-protected</code>, <code>-package</code>, |
|
57 and <code>-private</code>) filter program elements, producing a |
|
58 result 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> |
|
64 Throughout this API, the term <em>class</em> is normally a |
|
65 shorthand 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)}. |
|
68 In only a couple of other places, it means "class, as opposed to interface", |
|
69 as in: {@link com.sun.javadoc.Doc#isClass()}. |
|
70 In 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}. |
|
75 Throughout the API, the detailed description of each program element |
|
76 describes explicitly which meaning is being used. |
|
77 <p> |
|
78 |
|
79 <a name="qualified"></a> |
|
80 A <em>qualified</em> class or interface name is one that has its package |
|
81 name prepended to it, such as <code>java.lang.String</code>. A non-qualified |
|
82 name has no package name, such as <code>String</code>. |
|
83 <p> |
|
84 |
|
85 <a name="example"></a> |
|
86 <h3>Example</h3> |
|
87 |
|
88 The following is an example doclet that |
|
89 displays information in the <code>@param</code> tags of the processed |
|
90 classes: |
|
91 <pre> |
|
92 import com.sun.javadoc.*; |
|
93 |
|
94 public class ListParams extends <font color=red title="Doclet API">Doclet</font> { |
|
95 |
|
96 public static boolean start(<font color=red title="Doclet API">RootDoc</font> root) { |
|
97 <font color=red title="Doclet API">ClassDoc</font>[] classes = root.<font color=red title="Doclet API">classes</font>(); |
|
98 for (int i = 0; i < classes.length; ++i) { |
|
99 <font color=red title="Doclet API">ClassDoc</font> cd = classes[i]; |
|
100 printMembers(cd.<font color=red title="Doclet API">constructors</font>()); |
|
101 printMembers(cd.<font color=red title="Doclet API">methods</font>()); |
|
102 } |
|
103 return true; |
|
104 } |
|
105 |
|
106 static void printMembers(<font color=red title="Doclet API">ExecutableMemberDoc</font>[] mems) { |
|
107 for (int i = 0; i < mems.length; ++i) { |
|
108 <font color=red title="Doclet API">ParamTag</font>[] params = mems[i].<font color=red title="Doclet API">paramTags</font>(); |
|
109 System.out.println(mems[i].<font color=red title="Doclet API">qualifiedName</font>()); |
|
110 for (int j = 0; j < params.length; ++j) { |
|
111 System.out.println(" " + params[j].<font color=red title="Doclet API">parameterName</font>() |
|
112 + " - " + params[j].<font color=red title="Doclet API">parameterComment</font>()); |
|
113 } |
|
114 } |
|
115 } |
|
116 } |
|
117 </pre> |
|
118 Interfaces and methods from the Javadoc API are marked in |
|
119 <font color=red title="Doclet API">red</font>. |
|
120 {@link com.sun.javadoc.Doclet Doclet} is an abstract class that specifies |
|
121 the invocation interface for doclets, |
|
122 {@link com.sun.javadoc.Doclet Doclet} holds class or interface information, |
|
123 {@link com.sun.javadoc.ExecutableMemberDoc} is a |
|
124 superinterface of {@link com.sun.javadoc.MethodDoc} and |
|
125 {@link com.sun.javadoc.ConstructorDoc}, |
|
126 and {@link com.sun.javadoc.ParamTag} holds information |
|
127 from "<code>@param</code>" tags. |
|
128 <p> |
|
129 This doclet when invoked with a command line like: |
|
130 <pre> |
|
131 javadoc -doclet ListParams -sourcepath <source-location> java.util |
|
132 </pre> |
|
133 producing 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 |
|
148 package com.sun.javadoc; |