- /*
- * @(#)Tag.java 1.12 02/10/15
- *
- * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
- * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
- */
-
- package com.sun.javadoc;
-
- /**
- * Represents a simple documentation tag, such as @since, @author, @version.
- * Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since")
- * and tag text (e.g. "1.2"). Tags with structure or which require
- * special processing are handled by subclasses such as ParamTag
- * (for @param), SeeTag (for @see and {@link}), and ThrowsTag
- * (for @throws).
- *
- * @author Robert Field
- * @author Atul M Dambalkar
- * @see SeeTag
- * @see ParamTag
- * @see ThrowsTag
- * @see SerialFieldTag
- * @see Doc#tags()
- *
- */
- public interface Tag {
-
- /**
- * Return the name of this tag. The name is the string
- * starting with "@" that is used in a doc comment, such as
- * <code>@return</code>. For inline tags, such as
- * <code>{@link}</code>, the curly brackets
- * are not part of the name, so in this example the name
- * would be simply <code>@link</code>.
- */
- String name();
-
- /**
- * Return the containing {@link Doc} of this Tag element.
- */
- Doc holder();
-
- /**
- * Return the kind of this tag.
- * similar or synonymous tags. For most tags,
- * <code>kind() == name()</code>
- * the following table lists those cases where there is more
- * than one tag of a given kind:
- * <p>
- * <table border="1" cellpadding="4" cellspacing="0">
- * <tr><th><tt> kind() </th> <th><tt> name() </th></tr>
- * <tr><td><tt> @throws </td> <td><tt> @throws </td></tr>
- * <tr><td><tt> @throws </td> <td><tt> @exception </td></tr>
- * <tr><td><tt> @see </td> <td><tt> @see </td></tr>
- * <tr><td><tt> @see </td> <td><tt> @link </td></tr>
- * <tr><td><tt> @see </td> <td><tt> @linkplain </td></tr>
- * <tr><td><tt> @serial </td> <td><tt> @serial </td></tr>
- * <tr><td><tt> @serial </td> <td><tt> @serialData </td></tr>
- * </table>
- */
- String kind();
-
- /**
- * Return the text of this tag, that is, portion beyond tag name.
- */
- String text();
-
- /**
- * Convert this object to a string.
- */
- String toString();
-
- /**
- * For a documentation comment with embedded <code>{@link}</code>
- * tags, return an array of <code>Tag</code> objects. The entire
- * doc comment is broken down into strings separated by
- * <code>{@link}</code> tags, where each successive element
- * of the array represents either a string or
- * <code>{@link}</code> tag, in order, from start to end.
- * Each string is represented by a <code>Tag</code> object of
- * name "Text", where {@link #text()} returns the string. Each
- * <code>{@link}</code> tag is represented by a
- * {@link SeeTag} of name "@link" and kind "@see".
- * For example, given the following comment
- * tag:
- * <p>
- * <code>This is a {@link Doc commentlabel} example.</code>
- * <p>
- * return an array of Tag objects:
- * <ul>
- * <li> tags[0] is a {@link Tag} with name "Text" and text consisting
- * of "This is a "
- * <li> tags[1] is a {@link SeeTag} with name "@link", referenced
- * class <code>Doc</code> and label "commentlabel"
- * <li> tags[2] is a {@link Tag} with name "Text" and text consisting
- * of " example."
- * </ul>
- *
- * @return Tag[] array of tags
- * @see ParamTag
- * @see ThrowsTag
- */
- Tag[] inlineTags();
-
- /**
- * Return the first sentence of the comment as an array of tags.
- * Includes inline tags
- * (i.e. {@link <i>reference</i>} tags) but not
- * block tags.
- * Each section of plain text is represented as a {@link Tag}
- * of kind "Text".
- * Inline tags are represented as a {@link SeeTag} of kind "@link".
- * If the locale is English language, the first sentence is
- * determined by the rules described in the Java Language
- * Specification (first version): "This sentence ends
- * at the first period that is followed by a blank, tab, or
- * line terminator or at the first tagline.", in
- * addition a line will be terminated by paragraph and
- * section terminating HTML tags: <p> </p> <h1>
- * <h2> <h3> <h4> <h5> <h6>
- * <hr> <pre> or </pre>.
- * If the locale is not English, the sentence end will be
- * determined by
- * {@link java.text.BreakIterator#getSentenceInstance(Locale)
- * java.text.BreakIterator.getSentenceInstance(Locale)}.
- *
- * @return an array of {@link Tag} objects representing the
- * first sentence of the comment
- */
- Tag[] firstSentenceTags();
-
- /**
- * Return the source position of this tag.
- * @return the source position of this tag.
- */
- public SourcePosition position();
- }