0N/A/*
553N/A * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.
0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A *
0N/A * This code is free software; you can redistribute it and/or modify it
0N/A * under the terms of the GNU General Public License version 2 only, as
553N/A * published by the Free Software Foundation. Oracle designates this
0N/A * particular file as subject to the "Classpath" exception as provided
553N/A * by Oracle in the LICENSE file that accompanied this code.
0N/A *
0N/A * This code is distributed in the hope that it will be useful, but WITHOUT
0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0N/A * version 2 for more details (a copy is included in the LICENSE file that
0N/A * accompanied this code).
0N/A *
0N/A * You should have received a copy of the GNU General Public License version
0N/A * 2 along with this work; if not, write to the Free Software Foundation,
0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0N/A *
553N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
553N/A * or visit www.oracle.com if you need additional information or have any
553N/A * questions.
0N/A */
0N/A
0N/Apackage com.sun.javadoc;
0N/A
0N/Aimport java.text.BreakIterator;
0N/Aimport java.util.Locale;
0N/A
0N/A/**
0N/A * Represents Java language constructs (package, class, constructor,
0N/A * method, field) which have comments and have been processed by this
0N/A * run of javadoc. All Doc objects are unique, that is, they
0N/A * are == comparable.
0N/A *
0N/A * @since 1.2
0N/A * @author Robert Field
0N/A * @author Scott Seligman (generics, enums, annotations)
0N/A */
0N/Apublic interface Doc extends Comparable<Object> {
0N/A
0N/A /**
0N/A * Return the text of the comment for this doc item.
0N/A * Tags have been removed.
0N/A */
0N/A String commentText();
0N/A
0N/A /**
0N/A * Return all tags in this Doc item.
0N/A *
0N/A * @return an array of {@link Tag} objects containing all tags on
0N/A * this Doc item.
0N/A */
0N/A Tag[] tags();
0N/A
0N/A /**
0N/A * Return tags of the specified {@linkplain Tag#kind() kind} in
0N/A * this Doc item.
0N/A *
0N/A * For example, if 'tagname' has value "@serial", all tags in
0N/A * this Doc item of kind "@serial" will be returned.
0N/A *
0N/A * @param tagname name of the tag kind to search for.
0N/A * @return an array of Tag containing all tags whose 'kind()'
0N/A * matches 'tagname'.
0N/A */
0N/A Tag[] tags(String tagname);
0N/A
0N/A /**
0N/A * Return the see also tags in this Doc item.
0N/A *
0N/A * @return an array of SeeTag containing all @see tags.
0N/A */
0N/A SeeTag[] seeTags();
0N/A
0N/A /**
0N/A * Return comment as an array of tags. Includes inline tags
0N/A * (i.e. {&#64link <i>reference</i>} tags) but not
0N/A * block tags.
0N/A * Each section of plain text is represented as a {@link Tag}
0N/A * of {@linkplain Tag#kind() kind} "Text".
0N/A * Inline tags are represented as a {@link SeeTag} of kind "@see"
0N/A * and name "@link".
0N/A *
0N/A * @return an array of {@link Tag}s representing the comment
0N/A */
0N/A Tag[] inlineTags();
0N/A
0N/A /**
0N/A * Return the first sentence of the comment as an array of tags.
0N/A * Includes inline tags
0N/A * (i.e. {&#64link <i>reference</i>} tags) but not
0N/A * block tags.
0N/A * Each section of plain text is represented as a {@link Tag}
0N/A * of {@linkplain Tag#kind() kind} "Text".
0N/A * Inline tags are represented as a {@link SeeTag} of kind "@see"
0N/A * and name "@link".
0N/A * <p>
0N/A * If the locale is English language, the first sentence is
0N/A * determined by the rules described in the Java Language
0N/A * Specification (first version): &quot;This sentence ends
0N/A * at the first period that is followed by a blank, tab, or
0N/A * line terminator or at the first tagline.&quot;, in
0N/A * addition a line will be terminated by block
0N/A * HTML tags: &lt;p&gt; &lt;/p&gt; &lt;h1&gt;
0N/A * &lt;h2&gt; &lt;h3&gt; &lt;h4&gt; &lt;h5&gt; &lt;h6&gt;
0N/A * &lt;hr&gt; &lt;pre&gt; or &lt;/pre&gt;.
0N/A * If the locale is not English, the sentence end will be
0N/A * determined by
0N/A * {@link BreakIterator#getSentenceInstance(Locale)}.
0N/A
0N/A * @return an array of {@link Tag}s representing the
0N/A * first sentence of the comment
0N/A */
0N/A Tag[] firstSentenceTags();
0N/A
0N/A /**
0N/A * Return the full unprocessed text of the comment. Tags
0N/A * are included as text. Used mainly for store and retrieve
0N/A * operations like internalization.
0N/A */
0N/A String getRawCommentText();
0N/A
0N/A /**
0N/A * Set the full unprocessed text of the comment. Tags
0N/A * are included as text. Used mainly for store and retrieve
0N/A * operations like internalization.
0N/A */
0N/A void setRawCommentText(String rawDocumentation);
0N/A
0N/A /**
0N/A * Returns the non-qualified name of this Doc item.
0N/A *
0N/A * @return the name
0N/A */
0N/A String name();
0N/A
0N/A /**
0N/A * Compares this doc object with the specified object for order. Returns a
0N/A * negative integer, zero, or a positive integer as this doc object is less
0N/A * than, equal to, or greater than the given object.
0N/A * <p>
0N/A * This method satisfies the {@link java.lang.Comparable} interface.
0N/A *
0N/A * @param obj the <code>Object</code> to be compared.
0N/A * @return a negative integer, zero, or a positive integer as this Object
0N/A * is less than, equal to, or greater than the given Object.
0N/A * @exception ClassCastException the specified Object's type prevents it
0N/A * from being compared to this Object.
0N/A */
0N/A int compareTo(Object obj);
0N/A
0N/A /**
0N/A * Is this Doc item a field (but not an enum constant)?
0N/A *
0N/A * @return true if it represents a field
0N/A */
0N/A boolean isField();
0N/A
0N/A /**
0N/A * Is this Doc item an enum constant?
0N/A *
0N/A * @return true if it represents an enum constant
0N/A * @since 1.5
0N/A */
0N/A boolean isEnumConstant();
0N/A
0N/A /**
0N/A * Is this Doc item a constructor?
0N/A *
0N/A * @return true if it represents a constructor
0N/A */
0N/A boolean isConstructor();
0N/A
0N/A /**
0N/A * Is this Doc item a method (but not a constructor or annotation
0N/A * type element)?
0N/A *
0N/A * @return true if it represents a method
0N/A */
0N/A boolean isMethod();
0N/A
0N/A /**
0N/A * Is this Doc item an annotation type element?
0N/A *
0N/A * @return true if it represents an annotation type element
0N/A * @since 1.5
0N/A */
0N/A boolean isAnnotationTypeElement();
0N/A
0N/A /**
0N/A * Is this Doc item an interface (but not an annotation type)?
0N/A *
0N/A * @return true if it represents an interface
0N/A */
0N/A boolean isInterface();
0N/A
0N/A /**
0N/A * Is this Doc item an exception class?
0N/A *
0N/A * @return true if it represents an exception
0N/A */
0N/A boolean isException();
0N/A
0N/A /**
0N/A * Is this Doc item an error class?
0N/A *
0N/A * @return true if it represents a error
0N/A */
0N/A boolean isError();
0N/A
0N/A /**
0N/A * Is this Doc item an enum type?
0N/A *
0N/A * @return true if it represents an enum type
0N/A * @since 1.5
0N/A */
0N/A boolean isEnum();
0N/A
0N/A /**
0N/A * Is this Doc item an annotation type?
0N/A *
0N/A * @return true if it represents an annotation type
0N/A * @since 1.5
0N/A */
0N/A boolean isAnnotationType();
0N/A
0N/A /**
0N/A * Is this Doc item an
0N/A * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#class">ordinary
0N/A * class</a>?
0N/A * (i.e. not an interface, annotation type, enum, exception, or error)?
0N/A *
0N/A * @return true if it represents an ordinary class
0N/A */
0N/A boolean isOrdinaryClass();
0N/A
0N/A /**
0N/A * Is this Doc item a
0N/A * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#class">class</a>
0N/A * (and not an interface or annotation type)?
0N/A * This includes ordinary classes, enums, errors and exceptions.
0N/A *
0N/A * @return true if it represents a class
0N/A */
0N/A boolean isClass();
0N/A
0N/A /**
0N/A * Return true if this Doc item is
0N/A * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
0N/A * in the result set.
0N/A */
0N/A boolean isIncluded();
0N/A
0N/A /**
0N/A * Return the source position of the first line of the
0N/A * corresponding declaration, or null if
0N/A * no position is available. A default constructor returns
0N/A * null because it has no location in the source file.
0N/A *
0N/A * @since 1.4
0N/A */
0N/A SourcePosition position();
0N/A}