1 /* 2 * Copyright (c) 1997, 2018, 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 26 package com.sun.tools.javadoc.main; 27 28 import 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(since="9", forRemoval=true) 52 @SuppressWarnings("removal") 53 class TagImpl implements Tag { 54 55 protected final String text; 56 protected final String name; 57 protected final DocImpl holder; 58 59 /** 60 * Cached first sentence. 61 */ 62 private Tag[] firstSentence; 63 64 /** 65 * Cached inline tags. 66 */ 67 private Tag[] inlineTags; 68 69 /** 70 * Constructor 71 */ TagImpl(DocImpl holder, String name, String text)72 TagImpl(DocImpl holder, String name, String text) { 73 this.holder = holder; 74 this.name = name; 75 this.text = text; 76 } 77 78 /** 79 * Return the name of this tag. 80 */ name()81 public String name() { 82 return name; 83 } 84 85 /** 86 * Return the containing {@link Doc} of this Tag element. 87 */ holder()88 public Doc holder() { 89 return holder; 90 } 91 92 /** 93 * Return the kind of this tag. 94 */ kind()95 public String kind() { 96 return name; 97 } 98 99 /** 100 * Return the text of this tag, that is, portion beyond tag name. 101 */ text()102 public String text() { 103 return text; 104 } 105 docenv()106 DocEnv docenv() { 107 return holder.env; 108 } 109 110 /** 111 * for use by subclasses which have two part tag text. 112 */ divideAtWhite()113 String[] divideAtWhite() { 114 String[] sa = new String[2]; 115 int len = text.length(); 116 // if no white space found 117 sa[0] = text; 118 sa[1] = ""; 119 for (int inx = 0; inx < len; ++inx) { 120 char ch = text.charAt(inx); 121 if (Character.isWhitespace(ch)) { 122 sa[0] = text.substring(0, inx); 123 for (; inx < len; ++inx) { 124 ch = text.charAt(inx); 125 if (!Character.isWhitespace(ch)) { 126 sa[1] = text.substring(inx, len); 127 break; 128 } 129 } 130 break; 131 } 132 } 133 return sa; 134 } 135 136 /** 137 * convert this object to a string. 138 */ toString()139 public String toString() { 140 return name + ":" + text; 141 } 142 143 /** 144 * For documentation comment with embedded @link tags, return the array of 145 * TagImpls consisting of SeeTagImpl(s) and text containing TagImpl(s). 146 * Within a comment string "This is an example of inline tags for a 147 * documentation comment {@link Doc {@link Doc commentlabel}}", 148 * where inside the inner braces, the first "Doc" carries exctly the same 149 * syntax as a SeeTagImpl and the second "commentlabel" is label for the Html 150 * Link, will return an array of TagImpl(s) with first element as TagImpl with 151 * comment text "This is an example of inline tags for a documentation 152 * comment" and second element as SeeTagImpl with referenced class as "Doc" 153 * and the label for the Html Link as "commentlabel". 154 * 155 * @return TagImpl[] Array of tags with inline SeeTagImpls. 156 * @see ParamTagImpl 157 * @see ThrowsTagImpl 158 */ inlineTags()159 public Tag[] inlineTags() { 160 if (inlineTags == null) { 161 inlineTags = Comment.getInlineTags(holder, text); 162 } 163 return inlineTags; 164 } 165 166 /** 167 * Return array of tags for the first sentence in the doc comment text. 168 */ firstSentenceTags()169 public Tag[] firstSentenceTags() { 170 if (firstSentence == null) { 171 //Parse all sentences first to avoid duplicate warnings. 172 inlineTags(); 173 try { 174 docenv().setSilent(true); 175 firstSentence = Comment.firstSentenceTags(holder, text); 176 } finally { 177 docenv().setSilent(false); 178 } 179 } 180 return firstSentence; 181 } 182 183 /** 184 * Return the doc item to which this tag is attached. 185 * @return the doc item to which this tag is attached. 186 */ position()187 public SourcePosition position() { 188 return holder.position(); 189 } 190 } 191