1/*
2 * Copyright (c) 1997, 2012, 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 */
25
26package com.sun.tools.javadoc.main;
27
28import com.sun.javadoc.*;
29
30/**
31 * Represents a documentation tag, e.g. @since, @author, @version.
32 * Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since")
33 * and tag text (e.g. "1.2").  TagImpls with structure or which require
34 * special processing are handled by subclasses (ParamTagImpl, SeeTagImpl,
35 * and ThrowsTagImpl
36 *
37 *  <p><b>This is NOT part of any supported API.
38 *  If you write code that depends on this, you do so at your own risk.
39 *  This code and its internal interfaces are subject to change or
40 *  deletion without notice.</b>
41 *
42 * @author Robert Field
43 * @author Atul M Dambalkar
44 * @author Neal M Gafter
45 * @see SeeTagImpl
46 * @see ParamTagImpl
47 * @see ThrowsTagImpl
48 * @see Doc#tags()
49 *
50 */
51@Deprecated
52class TagImpl implements Tag {
53
54    protected final String text;
55    protected final String name;
56    protected final DocImpl holder;
57
58    /**
59     * Cached first sentence.
60     */
61    private Tag[] firstSentence;
62
63    /**
64     * Cached inline tags.
65     */
66    private Tag[] inlineTags;
67
68    /**
69     *  Constructor
70     */
71    TagImpl(DocImpl holder, String name, String text) {
72        this.holder = holder;
73        this.name = name;
74        this.text = text;
75    }
76
77    /**
78     * Return the name of this tag.
79     */
80    public String name() {
81        return name;
82    }
83
84    /**
85     * Return the containing {@link Doc} of this Tag element.
86     */
87    public Doc holder() {
88        return holder;
89    }
90
91    /**
92     * Return the kind of this tag.
93     */
94    public String kind() {
95        return name;
96    }
97
98    /**
99     * Return the text of this tag, that is, portion beyond tag name.
100     */
101    public String text() {
102        return text;
103    }
104
105    DocEnv docenv() {
106        return holder.env;
107    }
108
109    /**
110     * for use by subclasses which have two part tag text.
111     */
112    String[] divideAtWhite() {
113        String[] sa = new String[2];
114        int len = text.length();
115        // if no white space found
116        sa[0] = text;
117        sa[1] = "";
118        for (int inx = 0; inx < len; ++inx) {
119            char ch = text.charAt(inx);
120            if (Character.isWhitespace(ch)) {
121                sa[0] = text.substring(0, inx);
122                for (; inx < len; ++inx) {
123                    ch = text.charAt(inx);
124                    if (!Character.isWhitespace(ch)) {
125                        sa[1] = text.substring(inx, len);
126                        break;
127                    }
128                }
129                break;
130            }
131        }
132        return sa;
133    }
134
135    /**
136     * convert this object to a string.
137     */
138    public String toString() {
139        return name + ":" + text;
140    }
141
142    /**
143     * For documentation comment with embedded @link tags, return the array of
144     * TagImpls consisting of SeeTagImpl(s) and text containing TagImpl(s).
145     * Within a comment string "This is an example of inline tags for a
146     * documentation comment {@link Doc {@link Doc commentlabel}}",
147     * where inside the inner braces, the first "Doc" carries exctly the same
148     * syntax as a SeeTagImpl and the second "commentlabel" is label for the Html
149     * Link, will return an array of TagImpl(s) with first element as TagImpl with
150     * comment text "This is an example of inline tags for a documentation
151     * comment" and second element as SeeTagImpl with referenced class as "Doc"
152     * and the label for the Html Link as "commentlabel".
153     *
154     * @return TagImpl[] Array of tags with inline SeeTagImpls.
155     * @see ParamTagImpl
156     * @see ThrowsTagImpl
157     */
158    public Tag[] inlineTags() {
159        if (inlineTags == null) {
160            inlineTags = Comment.getInlineTags(holder, text);
161        }
162        return inlineTags;
163    }
164
165    /**
166     * Return array of tags for the first sentence in the doc comment text.
167     */
168    public Tag[] firstSentenceTags() {
169        if (firstSentence == null) {
170            //Parse all sentences first to avoid duplicate warnings.
171            inlineTags();
172            try {
173                docenv().setSilent(true);
174                firstSentence = Comment.firstSentenceTags(holder, text);
175            } finally {
176                docenv().setSilent(false);
177            }
178        }
179        return firstSentence;
180    }
181
182    /**
183     * Return the doc item to which this tag is attached.
184     * @return the doc item to which this tag is attached.
185     */
186    public SourcePosition position() {
187        return holder.position();
188    }
189}
190