Mercurial > jdk8-mips64-public > langtools / file comparison

comparison: src/share/classes/com/sun/javadoc/Doc.java

src/share/classes/com/sun/javadoc/Doc.java

changeset 1
9a66ca7c79fa
child 554
9d9f26857129
equal deleted inserted replaced
-1:000000000000 1:9a66ca7c79fa
1 /*
2 * Copyright 1998-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package com.sun.javadoc;
27
28 import java.text.BreakIterator;
29 import java.util.Locale;
30
31 /**
32 * Represents Java language constructs (package, class, constructor,
33 * method, field) which have comments and have been processed by this
34 * run of javadoc. All Doc objects are unique, that is, they
35 * are == comparable.
36 *
37 * @since 1.2
38 * @author Robert Field
39 * @author Scott Seligman (generics, enums, annotations)
40 */
41 public interface Doc extends Comparable<Object> {
42
43 /**
44 * Return the text of the comment for this doc item.
45 * Tags have been removed.
46 */
47 String commentText();
48
49 /**
50 * Return all tags in this Doc item.
51 *
52 * @return an array of {@link Tag} objects containing all tags on
53 * this Doc item.
54 */
55 Tag[] tags();
56
57 /**
58 * Return tags of the specified {@linkplain Tag#kind() kind} in
59 * this Doc item.
60 *
61 * For example, if 'tagname' has value "@serial", all tags in
62 * this Doc item of kind "@serial" will be returned.
63 *
64 * @param tagname name of the tag kind to search for.
65 * @return an array of Tag containing all tags whose 'kind()'
66 * matches 'tagname'.
67 */
68 Tag[] tags(String tagname);
69
70 /**
71 * Return the see also tags in this Doc item.
72 *
73 * @return an array of SeeTag containing all @see tags.
74 */
75 SeeTag[] seeTags();
76
77 /**
78 * Return comment as an array of tags. Includes inline tags
79 * (i.e. {&#64link <i>reference</i>} tags) but not
80 * block tags.
81 * Each section of plain text is represented as a {@link Tag}
82 * of {@linkplain Tag#kind() kind} "Text".
83 * Inline tags are represented as a {@link SeeTag} of kind "@see"
84 * and name "@link".
85 *
86 * @return an array of {@link Tag}s representing the comment
87 */
88 Tag[] inlineTags();
89
90 /**
91 * Return the first sentence of the comment as an array of tags.
92 * Includes inline tags
93 * (i.e. {&#64link <i>reference</i>} tags) but not
94 * block tags.
95 * Each section of plain text is represented as a {@link Tag}
96 * of {@linkplain Tag#kind() kind} "Text".
97 * Inline tags are represented as a {@link SeeTag} of kind "@see"
98 * and name "@link".
99 * <p>
100 * If the locale is English language, the first sentence is
101 * determined by the rules described in the Java Language
102 * Specification (first version): &quot;This sentence ends
103 * at the first period that is followed by a blank, tab, or
104 * line terminator or at the first tagline.&quot;, in
105 * addition a line will be terminated by block
106 * HTML tags: &lt;p&gt; &lt;/p&gt; &lt;h1&gt;
107 * &lt;h2&gt; &lt;h3&gt; &lt;h4&gt; &lt;h5&gt; &lt;h6&gt;
108 * &lt;hr&gt; &lt;pre&gt; or &lt;/pre&gt;.
109 * If the locale is not English, the sentence end will be
110 * determined by
111 * {@link BreakIterator#getSentenceInstance(Locale)}.
112
113 * @return an array of {@link Tag}s representing the
114 * first sentence of the comment
115 */
116 Tag[] firstSentenceTags();
117
118 /**
119 * Return the full unprocessed text of the comment. Tags
120 * are included as text. Used mainly for store and retrieve
121 * operations like internalization.
122 */
123 String getRawCommentText();
124
125 /**
126 * Set the full unprocessed text of the comment. Tags
127 * are included as text. Used mainly for store and retrieve
128 * operations like internalization.
129 */
130 void setRawCommentText(String rawDocumentation);
131
132 /**
133 * Returns the non-qualified name of this Doc item.
134 *
135 * @return the name
136 */
137 String name();
138
139 /**
140 * Compares this doc object with the specified object for order. Returns a
141 * negative integer, zero, or a positive integer as this doc object is less
142 * than, equal to, or greater than the given object.
143 * <p>
144 * This method satisfies the {@link java.lang.Comparable} interface.
145 *
146 * @param obj the <code>Object</code> to be compared.
147 * @return a negative integer, zero, or a positive integer as this Object
148 * is less than, equal to, or greater than the given Object.
149 * @exception ClassCastException the specified Object's type prevents it
150 * from being compared to this Object.
151 */
152 int compareTo(Object obj);
153
154 /**
155 * Is this Doc item a field (but not an enum constant)?
156 *
157 * @return true if it represents a field
158 */
159 boolean isField();
160
161 /**
162 * Is this Doc item an enum constant?
163 *
164 * @return true if it represents an enum constant
165 * @since 1.5
166 */
167 boolean isEnumConstant();
168
169 /**
170 * Is this Doc item a constructor?
171 *
172 * @return true if it represents a constructor
173 */
174 boolean isConstructor();
175
176 /**
177 * Is this Doc item a method (but not a constructor or annotation
178 * type element)?
179 *
180 * @return true if it represents a method
181 */
182 boolean isMethod();
183
184 /**
185 * Is this Doc item an annotation type element?
186 *
187 * @return true if it represents an annotation type element
188 * @since 1.5
189 */
190 boolean isAnnotationTypeElement();
191
192 /**
193 * Is this Doc item an interface (but not an annotation type)?
194 *
195 * @return true if it represents an interface
196 */
197 boolean isInterface();
198
199 /**
200 * Is this Doc item an exception class?
201 *
202 * @return true if it represents an exception
203 */
204 boolean isException();
205
206 /**
207 * Is this Doc item an error class?
208 *
209 * @return true if it represents a error
210 */
211 boolean isError();
212
213 /**
214 * Is this Doc item an enum type?
215 *
216 * @return true if it represents an enum type
217 * @since 1.5
218 */
219 boolean isEnum();
220
221 /**
222 * Is this Doc item an annotation type?
223 *
224 * @return true if it represents an annotation type
225 * @since 1.5
226 */
227 boolean isAnnotationType();
228
229 /**
230 * Is this Doc item an
231 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#class">ordinary
232 * class</a>?
233 * (i.e. not an interface, annotation type, enum, exception, or error)?
234 *
235 * @return true if it represents an ordinary class
236 */
237 boolean isOrdinaryClass();
238
239 /**
240 * Is this Doc item a
241 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#class">class</a>
242 * (and not an interface or annotation type)?
243 * This includes ordinary classes, enums, errors and exceptions.
244 *
245 * @return true if it represents a class
246 */
247 boolean isClass();
248
249 /**
250 * Return true if this Doc item is
251 * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
252 * in the result set.
253 */
254 boolean isIncluded();
255
256 /**
257 * Return the source position of the first line of the
258 * corresponding declaration, or null if
259 * no position is available. A default constructor returns
260 * null because it has no location in the source file.
261 *
262 * @since 1.4
263 */
264 SourcePosition position();
265 }

Mercurial Repository: jdk8-mips64-public/langtools

mercurial