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