/*
 * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.javadoc;

import java.text.BreakIterator;
import java.util.Locale;

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 ), and ThrowsTag (for @throws).
Author:Robert Field, Atul M Dambalkar
See Also:
Deprecated: The declarations in this package have been superseded by those in the package jdk.javadoc.doclet. For more information, see the Migration Guide in the documentation for that package.
/** * 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() * * @deprecated * The declarations in this package have been superseded by those * in the package {@code jdk.javadoc.doclet}. * For more information, see the <i>Migration Guide</i> in the documentation for that package. */
@Deprecated 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 @return. For inline tags, such as {@link}, the curly brackets are not part of the name, so in this example the name would be simply @link.
Returns:the name of this 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}. For inline tags, such as * {@code {@link}}, the curly brackets * are not part of the name, so in this example the name * would be simply {@code @link}. * * @return the name of this tag */
String name();
Return the containing Doc of this Tag element.
Returns:the containing Doc of this Tag element
/** * Return the containing {@link Doc} of this Tag element. * * @return the containing {@link Doc} of this Tag element */
Doc holder();
Return the kind of this tag. For most tags, kind() == name(); the following table lists those cases where there is more than one tag of a given kind:
Related Tags
kind() name()
@throws @throws
@throws @exception
@see @see
@see @link
@see @linkplain
@serial @serial
@serial @serialData
Returns:the kind of this tag.
/** * Return the kind of this tag. * For most tags, * {@code kind() == name()}; * the following table lists those cases where there is more * than one tag of a given kind: * * <table border="1"> * <caption>Related Tags</caption> * <tr><th>{@code kind() }</th> <th>{@code name() }</th></tr> * <tr><td>{@code @throws }</td> <td>{@code @throws }</td></tr> * <tr><td>{@code @throws }</td> <td>{@code @exception }</td></tr> * <tr><td>{@code @see }</td> <td>{@code @see }</td></tr> * <tr><td>{@code @see }</td> <td>{@code @link }</td></tr> * <tr><td>{@code @see }</td> <td>{@code @linkplain }</td></tr> * <tr><td>{@code @serial }</td> <td>{@code @serial }</td></tr> * <tr><td>{@code @serial }</td> <td>{@code @serialData }</td></tr> * </table> * * @return the kind of this tag. */
String kind();
Return the text of this tag, that is, the portion beyond tag name.
Returns:the text of this tag
/** * Return the text of this tag, that is, the portion beyond tag name. * * @return the text of this tag */
String text();
Convert this object to a string.
/** * Convert this object to a string. */
String toString();
For a documentation comment with embedded {@link} tags, return an array of Tag objects. The entire doc comment is broken down into strings separated by {@link} tags, where each successive element of the array represents either a string or {@link} tag, in order, from start to end. Each string is represented by a Tag object of name "Text", where text() returns the string. Each {@link} tag is represented by a SeeTag of name "@link" and kind "@see". For example, given the following comment tag:

This is a {@link Doc commentlabel} example.

return an array of Tag objects:

  • tags[0] is a Tag with name "Text" and text consisting of "This is a "
  • tags[1] is a SeeTag with name "@link", referenced class Doc and label "commentlabel"
  • tags[2] is a Tag with name "Text" and text consisting of " example."
See Also:
Returns:Tag[] array of tags
/** * For a documentation comment with embedded {@code {@link}} * tags, return an array of {@code Tag} objects. The entire * doc comment is broken down into strings separated by * {@code {@link}} tags, where each successive element * of the array represents either a string or * {@code {@link}} tag, in order, from start to end. * Each string is represented by a {@code Tag} object of * name "Text", where {@link #text()} returns the string. Each * {@code {@link}} 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.} * <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} 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 reference} tags) but not block tags. Each section of plain text is represented as a Tag of kind "Text". Inline tags are represented as a 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 BreakIterator.getSentenceInstance(Locale).
Returns:an array of Tag objects representing the first sentence of the comment
/** * Return the first sentence of the comment as an array of tags. * Includes inline tags * (i.e. {&#64;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): &quot;This sentence ends * at the first period that is followed by a blank, tab, or * line terminator or at the first tagline.&quot;, in * addition a line will be terminated by paragraph and * section terminating HTML tags: &lt;p&gt; &lt;/p&gt; &lt;h1&gt; * &lt;h2&gt; &lt;h3&gt; &lt;h4&gt; &lt;h5&gt; &lt;h6&gt; * &lt;hr&gt; &lt;pre&gt; or &lt;/pre&gt;. * If the locale is not English, the sentence end will be * determined by * {@link 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.
Returns:the source position of this tag.
/** * Return the source position of this tag. * @return the source position of this tag. */
public SourcePosition position(); }