001: /*
002: * Copyright 1997-2004 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.tools.javadoc;
027:
028: import com.sun.javadoc.*;
029:
030: /**
031: * Represents a documentation tag, e.g. @since, @author, @version.
032: * Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since")
033: * and tag text (e.g. "1.2"). TagImpls with structure or which require
034: * special processing are handled by subclasses (ParamTagImpl, SeeTagImpl,
035: * and ThrowsTagImpl
036: *
037: * @author Robert Field
038: * @author Atul M Dambalkar
039: * @author Neal M Gafter
040: * @see SeeTagImpl
041: * @see ParamTagImpl
042: * @see ThrowsTagImpl
043: * @see Doc#tags()
044: *
045: */
046: class TagImpl implements Tag {
047:
048: protected final String text;
049: protected final String name;
050: protected final DocImpl holder;
051:
052: /**
053: * Cached first sentence.
054: */
055: private Tag[] firstSentence;
056:
057: /**
058: * Cached inline tags.
059: */
060: private Tag[] inlineTags;
061:
062: /**
063: * Constructor
064: */
065: TagImpl(DocImpl holder, String name, String text) {
066: this .holder = holder;
067: this .name = name;
068: this .text = text;
069: }
070:
071: /**
072: * Return the name of this tag.
073: */
074: public String name() {
075: return name;
076: }
077:
078: /**
079: * Return the containing {@link Doc} of this Tag element.
080: */
081: public Doc holder() {
082: return holder;
083: }
084:
085: /**
086: * Return the kind of this tag.
087: */
088: public String kind() {
089: return name;
090: }
091:
092: /**
093: * Return the text of this tag, that is, portion beyond tag name.
094: */
095: public String text() {
096: return text;
097: }
098:
099: DocEnv docenv() {
100: return holder.env;
101: }
102:
103: /**
104: * for use by subclasses which have two part tag text.
105: */
106: String[] divideAtWhite() {
107: String[] sa = new String[2];
108: int len = text.length();
109: // if no white space found
110: sa[0] = text;
111: sa[1] = "";
112: for (int inx = 0; inx < len; ++inx) {
113: char ch = text.charAt(inx);
114: if (Character.isWhitespace(ch)) {
115: sa[0] = text.substring(0, inx);
116: for (; inx < len; ++inx) {
117: ch = text.charAt(inx);
118: if (!Character.isWhitespace(ch)) {
119: sa[1] = text.substring(inx, len);
120: break;
121: }
122: }
123: break;
124: }
125: }
126: return sa;
127: }
128:
129: /**
130: * convert this object to a string.
131: */
132: public String toString() {
133: return name + ":" + text;
134: }
135:
136: /**
137: * For documentation comment with embedded @link tags, return the array of
138: * TagImpls consisting of SeeTagImpl(s) and text containing TagImpl(s).
139: * Within a comment string "This is an example of inline tags for a
140: * documentation comment {@link Doc {@link Doc commentlabel}}",
141: * where inside the inner braces, the first "Doc" carries exctly the same
142: * syntax as a SeeTagImpl and the second "commentlabel" is label for the Html
143: * Link, will return an array of TagImpl(s) with first element as TagImpl with
144: * comment text "This is an example of inline tags for a documentation
145: * comment" and second element as SeeTagImpl with referenced class as "Doc"
146: * and the label for the Html Link as "commentlabel".
147: *
148: * @return TagImpl[] Array of tags with inline SeeTagImpls.
149: * @see ParamTagImpl
150: * @see ThrowsTagImpl
151: */
152: public Tag[] inlineTags() {
153: if (inlineTags == null) {
154: inlineTags = Comment.getInlineTags(holder, text);
155: }
156: return inlineTags;
157: }
158:
159: /**
160: * Return array of tags for the first sentence in the doc comment text.
161: */
162: public Tag[] firstSentenceTags() {
163: if (firstSentence == null) {
164: //Parse all sentences first to avoid duplicate warnings.
165: inlineTags();
166: try {
167: docenv().setSilent(true);
168: firstSentence = Comment.firstSentenceTags(holder, text);
169: } finally {
170: docenv().setSilent(false);
171: }
172: }
173: return firstSentence;
174: }
175:
176: /**
177: * Return the doc item to which this tag is attached.
178: * @return the doc item to which this tag is attached.
179: */
180: public SourcePosition position() {
181: return holder.position();
182: }
183: }
|