Mercurial > jdk8-mips64-public > langtools / file revision
src/share/classes/com/sun/javadoc/Doc.java@998b10c43157
src/share/classes/com/sun/javadoc/Doc.java
Tue, 24 Dec 2013 09:17:37 -0800
- author
- ksrini
- date
- Tue, 24 Dec 2013 09:17:37 -0800
- changeset 2227
- 998b10c43157
- parent 1326
- 30c36e23f154
- child 2525
- 2eb010b6cb22
- permissions
- -rw-r--r--
8029230: Update copyright year to match last edit in jdk8 langtools repository for 2013
Reviewed-by: ksrini
Contributed-by: steve.sides@oracle.com
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;
28 import java.text.BreakIterator;
29 import java.util.Locale;
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> {
43 /**
44 * Return the text of the comment for this doc item.
45 * Tags have been removed.
46 */
47 String commentText();
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();
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);
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();
77 /**
78 * Return comment as an array of tags. Includes inline tags
79 * (i.e. {@link <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();
90 /**
91 * Return the first sentence of the comment as an array of tags.
92 * Includes inline tags
93 * (i.e. {@link <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): "This sentence ends
103 * at the first period that is followed by a blank, tab, or
104 * line terminator or at the first tagline.", in
105 * addition a line will be terminated by block
106 * HTML tags: <p> </p> <h1>
107 * <h2> <h3> <h4> <h5> <h6>
108 * <hr> <pre> or </pre>.
109 * If the locale is not English, the sentence end will be
110 * determined by
111 * {@link BreakIterator#getSentenceInstance(Locale)}.
113 * @return an array of {@link Tag}s representing the
114 * first sentence of the comment
115 */
116 Tag[] firstSentenceTags();
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();
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);
132 /**
133 * Returns the non-qualified name of this Doc item.
134 *
135 * @return the name
136 */
137 String name();
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);
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();
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();
169 /**
170 * Is this Doc item a constructor?
171 *
172 * @return true if it represents a constructor
173 */
174 boolean isConstructor();
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();
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();
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();
199 /**
200 * Is this Doc item an exception class?
201 *
202 * @return true if it represents an exception
203 */
204 boolean isException();
206 /**
207 * Is this Doc item an error class?
208 *
209 * @return true if it represents a error
210 */
211 boolean isError();
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();
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();
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();
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();
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();
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 }
