KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > javadoc > Tag


1 /*
2  * @(#)Tag.java 1.12 02/10/15
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package com.sun.javadoc;
9
10 /**
11  * Represents a simple documentation tag, such as @since, @author, @version.
12  * Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since")
13  * and tag text (e.g. "1.2"). Tags with structure or which require
14  * special processing are handled by subclasses such as ParamTag
15  * (for @param), SeeTag (for @see and {@link}), and ThrowsTag
16  * (for @throws).
17  *
18  * @author Robert Field
19  * @author Atul M Dambalkar
20  * @see SeeTag
21  * @see ParamTag
22  * @see ThrowsTag
23  * @see SerialFieldTag
24  * @see Doc#tags()
25  *
26  */
27 public interface Tag {
28
29     /**
30      * Return the name of this tag. The name is the string
31      * starting with "@" that is used in a doc comment, such as
32      * <code>@return</code>. For inline tags, such as
33      * <code>{&#064;link}</code>, the curly brackets
34      * are not part of the name, so in this example the name
35      * would be simply <code>@link</code>.
36      */
37     String JavaDoc name();
38
39     /**
40      * Return the containing {@link Doc} of this Tag element.
41      */
42     Doc holder();
43
44     /**
45      * Return the kind of this tag.
46      * similar or synonymous tags. For most tags,
47      * <code>kind()&nbsp;==&nbsp;name()</code>;
48      * the following table lists those cases where there is more
49      * than one tag of a given kind:
50      * <p>
51      * <table border="1" cellpadding="4" cellspacing="0">
52      * <tr><th><tt> kind() </th> <th><tt> name() </th></tr>
53      * <tr><td><tt> @throws </td> <td><tt> @throws </td></tr>
54      * <tr><td><tt> @throws </td> <td><tt> @exception </td></tr>
55      * <tr><td><tt> @see </td> <td><tt> @see </td></tr>
56      * <tr><td><tt> @see </td> <td><tt> @link </td></tr>
57      * <tr><td><tt> @see </td> <td><tt> @linkplain </td></tr>
58      * <tr><td><tt> @serial </td> <td><tt> @serial </td></tr>
59      * <tr><td><tt> @serial </td> <td><tt> @serialData </td></tr>
60      * </table>
61      */
62     String JavaDoc kind();
63
64     /**
65      * Return the text of this tag, that is, portion beyond tag name.
66      */
67     String JavaDoc text();
68
69     /**
70      * Convert this object to a string.
71      */
72     String JavaDoc toString();
73
74     /**
75      * For a documentation comment with embedded <code>{&#064;link}</code>
76      * tags, return an array of <code>Tag</code> objects. The entire
77      * doc comment is broken down into strings separated by
78      * <code>{&#064;link}</code> tags, where each successive element
79      * of the array represents either a string or
80      * <code>{&#064;link}</code> tag, in order, from start to end.
81      * Each string is represented by a <code>Tag</code> object of
82      * name "Text", where {@link #text()} returns the string. Each
83      * <code>{&#064;link}</code> tag is represented by a
84      * {@link SeeTag} of name "@link" and kind "@see".
85      * For example, given the following comment
86      * tag:
87      * <p>
88      * <code>This is a {&#064;link Doc commentlabel} example.</code>
89      * <p>
90      * return an array of Tag objects:
91      * <ul>
92      * <li> tags[0] is a {@link Tag} with name "Text" and text consisting
93      * of "This is a "
94      * <li> tags[1] is a {@link SeeTag} with name "@link", referenced
95      * class <code>Doc</code> and label "commentlabel"
96      * <li> tags[2] is a {@link Tag} with name "Text" and text consisting
97      * of " example."
98      * </ul>
99      *
100      * @return Tag[] array of tags
101      * @see ParamTag
102      * @see ThrowsTag
103      */
104     Tag[] inlineTags();
105
106     /**
107      * Return the first sentence of the comment as an array of tags.
108      * Includes inline tags
109      * (i.e. {&#64link <i>reference</i>} tags) but not
110      * block tags.
111      * Each section of plain text is represented as a {@link Tag}
112      * of kind "Text".
113      * Inline tags are represented as a {@link SeeTag} of kind "@link".
114      * If the locale is English language, the first sentence is
115      * determined by the rules described in the Java Language
116      * Specification (first version): &quot;This sentence ends
117      * at the first period that is followed by a blank, tab, or
118      * line terminator or at the first tagline.&quot;, in
119      * addition a line will be terminated by paragraph and
120      * section terminating HTML tags: &lt;p&gt; &lt;/p&gt; &lt;h1&gt;
121      * &lt;h2&gt; &lt;h3&gt; &lt;h4&gt; &lt;h5&gt; &lt;h6&gt;
122      * &lt;hr&gt; &lt;pre&gt; or &lt;/pre&gt;.
123      * If the locale is not English, the sentence end will be
124      * determined by
125      * {@link java.text.BreakIterator#getSentenceInstance(Locale)
126      * java.text.BreakIterator.getSentenceInstance(Locale)}.
127      *
128      * @return an array of {@link Tag} objects representing the
129      * first sentence of the comment
130      */
131     Tag[] firstSentenceTags();
132
133     /**
134      * Return the source position of this tag.
135      * @return the source position of this tag.
136      */
137     public SourcePosition position();
138 }
139
Popular Tags