KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > javadoc > Doc


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