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