View Javadoc
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   */
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. {&#64;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();
89  
90      /**
91       * Return the first sentence of the comment as an array of tags.
92       * Includes inline tags
93       * (i.e. {&#64;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): &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 }