Tue, 22 Oct 2013 17:42:10 -0700
8027119: Cleanup javadoc comments for taglet API
Reviewed-by: mduigou
1 /*
2 * Copyright (c) 1998, 2012, 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 */
26 package com.sun.javadoc;
29 /**
30 * Represents a java class or interface and provides access to
31 * information about the class, the class's comment and tags, and the
32 * members of the class. A ClassDoc only exists if it was
33 * processed in this run of javadoc. References to classes
34 * which may or may not have been processed in this run are
35 * referred to using Type (which can be converted to ClassDoc,
36 * if possible).
37 *
38 * @see Type
39 *
40 * @since 1.2
41 * @author Kaiyang Liu (original)
42 * @author Robert Field (rewrite)
43 */
44 public interface ClassDoc extends ProgramElementDoc, Type {
46 /**
47 * Return true if this class is abstract. Return true
48 * for all interfaces.
49 */
50 boolean isAbstract();
52 /**
53 * Return true if this class implements or interface extends
54 * <code>java.io.Serializable</code>.
55 *
56 * Since <code>java.io.Externalizable</code> extends
57 * <code>java.io.Serializable</code>,
58 * Externalizable objects are also Serializable.
59 */
60 boolean isSerializable();
62 /**
63 * Return true if this class implements or interface extends
64 * <code>java.io.Externalizable</code>.
65 */
66 boolean isExternalizable();
68 /**
69 * Return true if this class can be used as a target type of a lambda expression
70 * or method reference.
71 */
72 boolean isFunctionalInterface();
74 /**
75 * Return the serialization methods for this class or
76 * interface.
77 *
78 * @return an array of MethodDoc objects that represents
79 * the serialization methods for this class or interface.
80 */
81 MethodDoc[] serializationMethods();
83 /**
84 * Return the Serializable fields of this class or interface.
85 * <p>
86 * Return either a list of default fields documented by
87 * <code>serial</code> tag<br>
88 * or return a single <code>FieldDoc</code> for
89 * <code>serialPersistentField</code> member.
90 * There should be a <code>serialField</code> tag for
91 * each Serializable field defined by an <code>ObjectStreamField</code>
92 * array component of <code>serialPersistentField</code>.
93 *
94 * @return an array of <code>FieldDoc</code> objects for the Serializable
95 * fields of this class or interface.
96 *
97 * @see #definesSerializableFields()
98 * @see SerialFieldTag
99 */
100 FieldDoc[] serializableFields();
102 /**
103 * Return true if Serializable fields are explicitly defined with
104 * the special class member <code>serialPersistentFields</code>.
105 *
106 * @see #serializableFields()
107 * @see SerialFieldTag
108 */
109 boolean definesSerializableFields();
111 /**
112 * Return the superclass of this class. Return null if this is an
113 * interface.
114 *
115 * <p> <i>This method cannot accommodate certain generic type constructs.
116 * The <code>superclassType</code> method should be used instead.</i>
117 *
118 * @return the ClassDoc for the superclass of this class, null if
119 * there is no superclass.
120 * @see #superclassType
121 */
122 ClassDoc superclass();
124 /**
125 * Return the superclass of this class. Return null if this is an
126 * interface. A superclass is represented by either a
127 * <code>ClassDoc</code> or a <code>ParametrizedType</code>.
128 *
129 * @return the superclass of this class, or null if there is no superclass.
130 * @since 1.5
131 */
132 Type superclassType();
134 /**
135 * Test whether this class is a subclass of the specified class.
136 * If this is an interface, return false for all classes except
137 * <code>java.lang.Object</code> (we must keep this unexpected
138 * behavior for compatibility reasons).
139 *
140 * @param cd the candidate superclass.
141 * @return true if cd is a superclass of this class.
142 */
143 boolean subclassOf(ClassDoc cd);
145 /**
146 * Return interfaces implemented by this class or interfaces extended
147 * by this interface. Includes only directly-declared interfaces, not
148 * inherited interfaces.
149 * Return an empty array if there are no interfaces.
150 *
151 * <p> <i>This method cannot accommodate certain generic type constructs.
152 * The <code>interfaceTypes</code> method should be used instead.</i>
153 *
154 * @return an array of ClassDoc objects representing the interfaces.
155 * @see #interfaceTypes
156 */
157 ClassDoc[] interfaces();
159 /**
160 * Return interfaces implemented by this class or interfaces extended
161 * by this interface. Includes only directly-declared interfaces, not
162 * inherited interfaces.
163 * Return an empty array if there are no interfaces.
164 *
165 * @return an array of interfaces, each represented by a
166 * <code>ClassDoc</code> or a <code>ParametrizedType</code>.
167 * @since 1.5
168 */
169 Type[] interfaceTypes();
171 /**
172 * Return the formal type parameters of this class or interface.
173 * Return an empty array if there are none.
174 *
175 * @return the formal type parameters of this class or interface.
176 * @since 1.5
177 */
178 TypeVariable[] typeParameters();
180 /**
181 * Return the type parameter tags of this class or interface.
182 * Return an empty array if there are none.
183 *
184 * @return the type parameter tags of this class or interface.
185 * @since 1.5
186 */
187 ParamTag[] typeParamTags();
189 /**
190 * Return
191 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
192 * fields in this class or interface.
193 * Excludes enum constants if this is an enum type.
194 *
195 * @return an array of FieldDoc objects representing the included
196 * fields in this class or interface.
197 */
198 FieldDoc[] fields();
200 /**
201 * Return fields in this class or interface, filtered to the specified
202 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access
203 * modifier option</a>.
204 * Excludes enum constants if this is an enum type.
205 *
206 * @param filter Specify true to filter according to the specified access
207 * modifier option.
208 * Specify false to include all fields regardless of
209 * access modifier option.
210 * @return an array of FieldDoc objects representing the included
211 * fields in this class or interface.
212 */
213 FieldDoc[] fields(boolean filter);
215 /**
216 * Return the enum constants if this is an enum type.
217 * Return an empty array if there are no enum constants, or if
218 * this is not an enum type.
219 *
220 * @return the enum constants if this is an enum type.
221 */
222 FieldDoc[] enumConstants();
224 /**
225 * Return
226 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
227 * methods in this class or interface.
228 * Same as <code>methods(true)</code>.
229 *
230 * @return an array of MethodDoc objects representing the included
231 * methods in this class or interface. Does not include
232 * constructors or annotation type elements.
233 */
234 MethodDoc[] methods();
236 /**
237 * Return methods in this class or interface, filtered to the specified
238 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access
239 * modifier option</a>. Does not include constructors or annotation
240 * type elements.
241 *
242 * @param filter Specify true to filter according to the specified access
243 * modifier option.
244 * Specify false to include all methods regardless of
245 * access modifier option.
246 * @return an array of MethodDoc objects representing the included
247 * methods in this class or interface.
248 */
249 MethodDoc[] methods(boolean filter);
251 /**
252 * Return
253 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
254 * constructors in this class. An array containing the default
255 * no-arg constructor is returned if no other constructors exist.
256 * Return empty array if this is an interface.
257 *
258 * @return an array of ConstructorDoc objects representing the included
259 * constructors in this class.
260 */
261 ConstructorDoc[] constructors();
263 /**
264 * Return constructors in this class, filtered to the specified
265 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access
266 * modifier option</a>. Return an array containing the default
267 * no-arg constructor if no other constructors exist.
268 *
269 * @param filter Specify true to filter according to the specified access
270 * modifier option.
271 * Specify false to include all constructors regardless of
272 * access modifier option.
273 * @return an array of ConstructorDoc objects representing the included
274 * constructors in this class.
275 */
276 ConstructorDoc[] constructors(boolean filter);
279 /**
280 * Return
281 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
282 * nested classes and interfaces within this class or interface.
283 * This includes both static and non-static nested classes.
284 * (This method should have been named <code>nestedClasses()</code>,
285 * as inner classes are technically non-static.) Anonymous and local classes
286 * or interfaces are not included.
287 *
288 * @return an array of ClassDoc objects representing the included classes
289 * and interfaces defined in this class or interface.
290 */
291 ClassDoc[] innerClasses();
293 /**
294 * Return nested classes and interfaces within this class or interface
295 * filtered to the specified
296 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access
297 * modifier option</a>.
298 * This includes both static and non-static nested classes.
299 * Anonymous and local classes are not included.
300 *
301 * @param filter Specify true to filter according to the specified access
302 * modifier option.
303 * Specify false to include all nested classes regardless of
304 * access modifier option.
305 * @return a filtered array of ClassDoc objects representing the included
306 * classes and interfaces defined in this class or interface.
307 */
308 ClassDoc[] innerClasses(boolean filter);
310 /**
311 * Find the specified class or interface within the context of this class doc.
312 * Search order: 1) qualified name, 2) nested in this class or interface,
313 * 3) in this package, 4) in the class imports, 5) in the package imports.
314 * Return the ClassDoc if found, null if not found.
315 */
316 ClassDoc findClass(String className);
318 /**
319 * Get the list of classes and interfaces declared as imported.
320 * These are called "single-type-import declarations" in
321 * <cite>The Java™ Language Specification</cite>.
322 *
323 * @return an array of ClassDoc representing the imported classes.
324 *
325 * @deprecated Import declarations are implementation details that
326 * should not be exposed here. In addition, not all imported
327 * classes are imported through single-type-import declarations.
328 */
329 @Deprecated
330 ClassDoc[] importedClasses();
332 /**
333 * Get the list of packages declared as imported.
334 * These are called "type-import-on-demand declarations" in
335 * <cite>The Java™ Language Specification</cite>.
336 *
337 * @return an array of PackageDoc representing the imported packages.
338 *
339 * @deprecated Import declarations are implementation details that
340 * should not be exposed here. In addition, this method's
341 * return type does not allow for all type-import-on-demand
342 * declarations to be returned.
343 */
344 @Deprecated
345 PackageDoc[] importedPackages();
346 }