duke@1: /* jjg@1326: * Copyright (c) 1998, 2012, Oracle and/or its affiliates. All rights reserved. duke@1: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. duke@1: * duke@1: * This code is free software; you can redistribute it and/or modify it duke@1: * under the terms of the GNU General Public License version 2 only, as ohair@554: * published by the Free Software Foundation. Oracle designates this duke@1: * particular file as subject to the "Classpath" exception as provided ohair@554: * by Oracle in the LICENSE file that accompanied this code. duke@1: * duke@1: * This code is distributed in the hope that it will be useful, but WITHOUT duke@1: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or duke@1: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License duke@1: * version 2 for more details (a copy is included in the LICENSE file that duke@1: * accompanied this code). duke@1: * duke@1: * You should have received a copy of the GNU General Public License version duke@1: * 2 along with this work; if not, write to the Free Software Foundation, duke@1: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. duke@1: * ohair@554: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@554: * or visit www.oracle.com if you need additional information or have any ohair@554: * questions. duke@1: */ duke@1: duke@1: package com.sun.javadoc; duke@1: duke@1: import java.text.BreakIterator; duke@1: import java.util.Locale; duke@1: duke@1: /** duke@1: * Represents Java language constructs (package, class, constructor, duke@1: * method, field) which have comments and have been processed by this duke@1: * run of javadoc. All Doc objects are unique, that is, they duke@1: * are == comparable. duke@1: * duke@1: * @since 1.2 duke@1: * @author Robert Field duke@1: * @author Scott Seligman (generics, enums, annotations) duke@1: */ duke@1: public interface Doc extends Comparable { duke@1: duke@1: /** duke@1: * Return the text of the comment for this doc item. duke@1: * Tags have been removed. duke@1: */ duke@1: String commentText(); duke@1: duke@1: /** duke@1: * Return all tags in this Doc item. duke@1: * duke@1: * @return an array of {@link Tag} objects containing all tags on duke@1: * this Doc item. duke@1: */ duke@1: Tag[] tags(); duke@1: duke@1: /** duke@1: * Return tags of the specified {@linkplain Tag#kind() kind} in duke@1: * this Doc item. duke@1: * duke@1: * For example, if 'tagname' has value "@serial", all tags in duke@1: * this Doc item of kind "@serial" will be returned. duke@1: * duke@1: * @param tagname name of the tag kind to search for. duke@1: * @return an array of Tag containing all tags whose 'kind()' duke@1: * matches 'tagname'. duke@1: */ duke@1: Tag[] tags(String tagname); duke@1: duke@1: /** duke@1: * Return the see also tags in this Doc item. duke@1: * duke@1: * @return an array of SeeTag containing all @see tags. duke@1: */ duke@1: SeeTag[] seeTags(); duke@1: duke@1: /** duke@1: * Return comment as an array of tags. Includes inline tags jjg@1326: * (i.e. {@link reference} tags) but not duke@1: * block tags. duke@1: * Each section of plain text is represented as a {@link Tag} duke@1: * of {@linkplain Tag#kind() kind} "Text". duke@1: * Inline tags are represented as a {@link SeeTag} of kind "@see" duke@1: * and name "@link". duke@1: * duke@1: * @return an array of {@link Tag}s representing the comment duke@1: */ duke@1: Tag[] inlineTags(); duke@1: duke@1: /** duke@1: * Return the first sentence of the comment as an array of tags. duke@1: * Includes inline tags jjg@1326: * (i.e. {@link reference} tags) but not duke@1: * block tags. duke@1: * Each section of plain text is represented as a {@link Tag} duke@1: * of {@linkplain Tag#kind() kind} "Text". duke@1: * Inline tags are represented as a {@link SeeTag} of kind "@see" duke@1: * and name "@link". duke@1: *

duke@1: * If the locale is English language, the first sentence is duke@1: * determined by the rules described in the Java Language duke@1: * Specification (first version): "This sentence ends duke@1: * at the first period that is followed by a blank, tab, or duke@1: * line terminator or at the first tagline.", in duke@1: * addition a line will be terminated by block duke@1: * HTML tags: <p> </p> <h1> duke@1: * <h2> <h3> <h4> <h5> <h6> duke@1: * <hr> <pre> or </pre>. duke@1: * If the locale is not English, the sentence end will be duke@1: * determined by duke@1: * {@link BreakIterator#getSentenceInstance(Locale)}. duke@1: duke@1: * @return an array of {@link Tag}s representing the duke@1: * first sentence of the comment duke@1: */ duke@1: Tag[] firstSentenceTags(); duke@1: duke@1: /** duke@1: * Return the full unprocessed text of the comment. Tags duke@1: * are included as text. Used mainly for store and retrieve duke@1: * operations like internalization. duke@1: */ duke@1: String getRawCommentText(); duke@1: duke@1: /** duke@1: * Set the full unprocessed text of the comment. Tags duke@1: * are included as text. Used mainly for store and retrieve duke@1: * operations like internalization. duke@1: */ duke@1: void setRawCommentText(String rawDocumentation); duke@1: duke@1: /** duke@1: * Returns the non-qualified name of this Doc item. duke@1: * duke@1: * @return the name duke@1: */ duke@1: String name(); duke@1: duke@1: /** duke@1: * Compares this doc object with the specified object for order. Returns a duke@1: * negative integer, zero, or a positive integer as this doc object is less duke@1: * than, equal to, or greater than the given object. duke@1: *

duke@1: * This method satisfies the {@link java.lang.Comparable} interface. duke@1: * duke@1: * @param obj the Object to be compared. duke@1: * @return a negative integer, zero, or a positive integer as this Object duke@1: * is less than, equal to, or greater than the given Object. duke@1: * @exception ClassCastException the specified Object's type prevents it duke@1: * from being compared to this Object. duke@1: */ duke@1: int compareTo(Object obj); duke@1: duke@1: /** duke@1: * Is this Doc item a field (but not an enum constant)? duke@1: * duke@1: * @return true if it represents a field duke@1: */ duke@1: boolean isField(); duke@1: duke@1: /** duke@1: * Is this Doc item an enum constant? duke@1: * duke@1: * @return true if it represents an enum constant duke@1: * @since 1.5 duke@1: */ duke@1: boolean isEnumConstant(); duke@1: duke@1: /** duke@1: * Is this Doc item a constructor? duke@1: * duke@1: * @return true if it represents a constructor duke@1: */ duke@1: boolean isConstructor(); duke@1: duke@1: /** duke@1: * Is this Doc item a method (but not a constructor or annotation duke@1: * type element)? duke@1: * duke@1: * @return true if it represents a method duke@1: */ duke@1: boolean isMethod(); duke@1: duke@1: /** duke@1: * Is this Doc item an annotation type element? duke@1: * duke@1: * @return true if it represents an annotation type element duke@1: * @since 1.5 duke@1: */ duke@1: boolean isAnnotationTypeElement(); duke@1: duke@1: /** duke@1: * Is this Doc item an interface (but not an annotation type)? duke@1: * duke@1: * @return true if it represents an interface duke@1: */ duke@1: boolean isInterface(); duke@1: duke@1: /** duke@1: * Is this Doc item an exception class? duke@1: * duke@1: * @return true if it represents an exception duke@1: */ duke@1: boolean isException(); duke@1: duke@1: /** duke@1: * Is this Doc item an error class? duke@1: * duke@1: * @return true if it represents a error duke@1: */ duke@1: boolean isError(); duke@1: duke@1: /** duke@1: * Is this Doc item an enum type? duke@1: * duke@1: * @return true if it represents an enum type duke@1: * @since 1.5 duke@1: */ duke@1: boolean isEnum(); duke@1: duke@1: /** duke@1: * Is this Doc item an annotation type? duke@1: * duke@1: * @return true if it represents an annotation type duke@1: * @since 1.5 duke@1: */ duke@1: boolean isAnnotationType(); duke@1: duke@1: /** duke@1: * Is this Doc item an duke@1: * ordinary duke@1: * class? duke@1: * (i.e. not an interface, annotation type, enum, exception, or error)? duke@1: * duke@1: * @return true if it represents an ordinary class duke@1: */ duke@1: boolean isOrdinaryClass(); duke@1: duke@1: /** duke@1: * Is this Doc item a duke@1: * class duke@1: * (and not an interface or annotation type)? duke@1: * This includes ordinary classes, enums, errors and exceptions. duke@1: * duke@1: * @return true if it represents a class duke@1: */ duke@1: boolean isClass(); duke@1: duke@1: /** duke@1: * Return true if this Doc item is duke@1: * included duke@1: * in the result set. duke@1: */ duke@1: boolean isIncluded(); duke@1: duke@1: /** duke@1: * Return the source position of the first line of the duke@1: * corresponding declaration, or null if duke@1: * no position is available. A default constructor returns duke@1: * null because it has no location in the source file. duke@1: * duke@1: * @since 1.4 duke@1: */ duke@1: SourcePosition position(); duke@1: }