jdk8-mips64-public/langtools: src/share/classes/com/sun/javadoc/Tag.java@2eb010b6cb22

     1 /*

     2  * Copyright (c) 1998, 2013, 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  */

    26 package com.sun.javadoc;

    28 import java.text.BreakIterator;

    29 import java.util.Locale;

    31 /**

    32  * Represents a simple documentation tag, such as @since, @author, @version.

    33  * Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since")

    34  * and tag text (e.g. "1.2").  Tags with structure or which require

    35  * special processing are handled by subclasses such as ParamTag

    36  * (for @param), SeeTag (for @see and {&#064;link}), and ThrowsTag

    37  * (for @throws).

    38  *

    39  * @author Robert Field

    40  * @author Atul M Dambalkar

    41  * @see SeeTag

    42  * @see ParamTag

    43  * @see ThrowsTag

    44  * @see SerialFieldTag

    45  * @see Doc#tags()

    46  *

    47  */

    48 public interface Tag {

    50     /**

    51      * Return the name of this tag.  The name is the string

    52      * starting with "@" that is used in a doc comment, such as

    53      * <code>@return</code>.  For inline tags, such as

    54      * <code>{&#064;link}</code>, the curly brackets

    55      * are not part of the name, so in this example the name

    56      * would be simply <code>@link</code>.

    57      *

    58      * @return the name of this tag

    59      */

    60     String name();

    62     /**

    63      * Return the containing {@link Doc} of this Tag element.

    64      *

    65      * @return the containing {@link Doc} of this Tag element

    66      */

    67     Doc holder();

    69     /**

    70      * Return the kind of this tag.

    71      * For most tags,

    72      * <code>kind()&nbsp;==&nbsp;name()</code>;

    73      * the following table lists those cases where there is more

    74      * than one tag of a given kind:

    75      *

    76      * <table border="1" cellpadding="4" cellspacing="0" summary="related tags">

    77      * <tr><th>{@code kind()  }</th>  <th>{@code name()      }</th></tr>

    78      * <tr><td>{@code @throws }</td>  <td>{@code @throws     }</td></tr>

    79      * <tr><td>{@code @throws }</td>  <td>{@code @exception  }</td></tr>

    80      * <tr><td>{@code @see    }</td>  <td>{@code @see        }</td></tr>

    81      * <tr><td>{@code @see    }</td>  <td>{@code @link       }</td></tr>

    82      * <tr><td>{@code @see    }</td>  <td>{@code @linkplain  }</td></tr>

    83      * <tr><td>{@code @serial }</td>  <td>{@code @serial     }</td></tr>

    84      * <tr><td>{@code @serial }</td>  <td>{@code @serialData }</td></tr>

    85      * </table>

    86      *

    87      * @return the kind of this tag.

    88      */

    89     String kind();

    91     /**

    92      * Return the text of this tag, that is, the portion beyond tag name.

    93      *

    94      * @return the text of this tag

    95      */

    96     String text();

    98     /**

    99      * Convert this object to a string.

   100      */

   101     String toString();

   103     /**

   104      * For a documentation comment with embedded <code>{&#064;link}</code>

   105      * tags, return an array of <code>Tag</code> objects.  The entire

   106      * doc comment is broken down into strings separated by

   107      * <code>{&#064;link}</code> tags, where each successive element

   108      * of the array represents either a string or

   109      * <code>{&#064;link}</code> tag, in order, from start to end.

   110      * Each string is represented by a <code>Tag</code> object of

   111      * name "Text", where {@link #text()} returns the string.  Each

   112      * <code>{&#064;link}</code> tag is represented by a

   113      * {@link SeeTag} of name "@link" and kind "@see".

   114      * For example, given the following comment

   115      * tag:

   116      * <p>

   117      *  <code>This is a {&#064;link Doc commentlabel} example.</code>

   118      * <p>

   119      * return an array of Tag objects:

   120      * <ul>

   121      *    <li> tags[0] is a {@link Tag} with name "Text" and text consisting

   122      *         of "This is a "

   123      *    <li> tags[1] is a {@link SeeTag} with name "@link", referenced

   124      *         class <code>Doc</code> and label "commentlabel"

   125      *    <li> tags[2] is a {@link Tag} with name "Text" and text consisting

   126      *         of " example."

   127      * </ul>

   128      *

   129      * @return Tag[] array of tags

   130      * @see ParamTag

   131      * @see ThrowsTag

   132      */

   133     Tag[] inlineTags();

   135     /**

   136      * Return the first sentence of the comment as an array of tags.

   137      * Includes inline tags

   138      * (i.e. {&#64;link <i>reference</i>} tags)  but not

   139      * block tags.

   140      * Each section of plain text is represented as a {@link Tag}

   141      * of kind "Text".

   142      * Inline tags are represented as a {@link SeeTag} of kind "@link".

   143      * If the locale is English language, the first sentence is

   144      * determined by the rules described in the Java Language

   145      * Specification (first version): &quot;This sentence ends

   146      * at the first period that is followed by a blank, tab, or

   147      * line terminator or at the first tagline.&quot;, in

   148      * addition a line will be terminated by paragraph and

   149      * section terminating HTML tags: &lt;p&gt;  &lt;/p&gt;  &lt;h1&gt;

   150      * &lt;h2&gt;  &lt;h3&gt; &lt;h4&gt;  &lt;h5&gt;  &lt;h6&gt;

   151      * &lt;hr&gt;  &lt;pre&gt;  or &lt;/pre&gt;.

   152      * If the locale is not English, the sentence end will be

   153      * determined by

   154      * {@link BreakIterator#getSentenceInstance(Locale)}.

   155      *

   156      * @return an array of {@link Tag} objects representing the

   157      *         first sentence of the comment

   158      */

   159     Tag[] firstSentenceTags();

   161     /**

   162      * Return the source position of this tag.

   163      * @return the source position of this tag.

   164      */

   165     public SourcePosition position();

   166 }

Mercurial > jdk8-mips64-public > langtools / file revision