Thu, 04 Jul 2013 10:35:33 +0100
8009924: some langtools tools do not accept -cp as an alias for -classpath
Reviewed-by: jjg
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 {@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 * @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() == name()</code>;
73 * the following table lists those cases where there is more
74 * than one tag of a given kind:
75 * <p>
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>{@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>{@link}</code> tags, where each successive element
108 * of the array represents either a string or
109 * <code>{@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>{@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 {@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. {@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): "This sentence ends
146 * at the first period that is followed by a blank, tab, or
147 * line terminator or at the first tagline.", in
148 * addition a line will be terminated by paragraph and
149 * section terminating HTML tags: <p> </p> <h1>
150 * <h2> <h3> <h4> <h5> <h6>
151 * <hr> <pre> or </pre>.
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 }