Mercurial > jdk8-mips64-public > langtools / file revision
src/share/classes/com/sun/javadoc/Tag.java@9a66ca7c79fa
src/share/classes/com/sun/javadoc/Tag.java
Sat, 01 Dec 2007 00:00:00 +0000
- author
- duke
- date
- Sat, 01 Dec 2007 00:00:00 +0000
- changeset 1
- 9a66ca7c79fa
- child 554
- 9d9f26857129
- permissions
- -rw-r--r--
Initial load
1 /*
2 * Copyright 1998-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 {@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>{@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 String name();
60 /**
61 * Return the containing {@link Doc} of this Tag element.
62 */
63 Doc holder();
65 /**
66 * Return the kind of this tag.
67 * similar or synonymous tags. For most tags,
68 * <code>kind() == name()</code>;
69 * the following table lists those cases where there is more
70 * than one tag of a given kind:
71 * <p>
72 * <table border="1" cellpadding="4" cellspacing="0">
73 * <tr><th><tt> kind() </th> <th><tt> name() </th></tr>
74 * <tr><td><tt> @throws </td> <td><tt> @throws </td></tr>
75 * <tr><td><tt> @throws </td> <td><tt> @exception </td></tr>
76 * <tr><td><tt> @see </td> <td><tt> @see </td></tr>
77 * <tr><td><tt> @see </td> <td><tt> @link </td></tr>
78 * <tr><td><tt> @see </td> <td><tt> @linkplain </td></tr>
79 * <tr><td><tt> @serial </td> <td><tt> @serial </td></tr>
80 * <tr><td><tt> @serial </td> <td><tt> @serialData </td></tr>
81 * </table>
82 */
83 String kind();
85 /**
86 * Return the text of this tag, that is, portion beyond tag name.
87 */
88 String text();
90 /**
91 * Convert this object to a string.
92 */
93 String toString();
95 /**
96 * For a documentation comment with embedded <code>{@link}</code>
97 * tags, return an array of <code>Tag</code> objects. The entire
98 * doc comment is broken down into strings separated by
99 * <code>{@link}</code> tags, where each successive element
100 * of the array represents either a string or
101 * <code>{@link}</code> tag, in order, from start to end.
102 * Each string is represented by a <code>Tag</code> object of
103 * name "Text", where {@link #text()} returns the string. Each
104 * <code>{@link}</code> tag is represented by a
105 * {@link SeeTag} of name "@link" and kind "@see".
106 * For example, given the following comment
107 * tag:
108 * <p>
109 * <code>This is a {@link Doc commentlabel} example.</code>
110 * <p>
111 * return an array of Tag objects:
112 * <ul>
113 * <li> tags[0] is a {@link Tag} with name "Text" and text consisting
114 * of "This is a "
115 * <li> tags[1] is a {@link SeeTag} with name "@link", referenced
116 * class <code>Doc</code> and label "commentlabel"
117 * <li> tags[2] is a {@link Tag} with name "Text" and text consisting
118 * of " example."
119 * </ul>
120 *
121 * @return Tag[] array of tags
122 * @see ParamTag
123 * @see ThrowsTag
124 */
125 Tag[] inlineTags();
127 /**
128 * Return the first sentence of the comment as an array of tags.
129 * Includes inline tags
130 * (i.e. {@link <i>reference</i>} tags) but not
131 * block tags.
132 * Each section of plain text is represented as a {@link Tag}
133 * of kind "Text".
134 * Inline tags are represented as a {@link SeeTag} of kind "@link".
135 * If the locale is English language, the first sentence is
136 * determined by the rules described in the Java Language
137 * Specification (first version): "This sentence ends
138 * at the first period that is followed by a blank, tab, or
139 * line terminator or at the first tagline.", in
140 * addition a line will be terminated by paragraph and
141 * section terminating HTML tags: <p> </p> <h1>
142 * <h2> <h3> <h4> <h5> <h6>
143 * <hr> <pre> or </pre>.
144 * If the locale is not English, the sentence end will be
145 * determined by
146 * {@link BreakIterator#getSentenceInstance(Locale)}.
147 *
148 * @return an array of {@link Tag} objects representing the
149 * first sentence of the comment
150 */
151 Tag[] firstSentenceTags();
153 /**
154 * Return the source position of this tag.
155 * @return the source position of this tag.
156 */
157 public SourcePosition position();
158 }
