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