1/* 2 * Copyright (c) 2001, 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 */ 25 26package com.sun.tools.doclets.internal.toolkit.taglets; 27 28import com.sun.javadoc.*; 29import com.sun.tools.doclets.internal.toolkit.Content; 30import com.sun.tools.doclets.internal.toolkit.util.DocFinder; 31import com.sun.tools.javac.util.StringUtils; 32 33/** 34 * A simple single argument custom tag. 35 * 36 * <p><b>This is NOT part of any supported API. 37 * If you write code that depends on this, you do so at your own risk. 38 * This code and its internal interfaces are subject to change or 39 * deletion without notice.</b> 40 * 41 * @author Jamie Ho 42 */ 43 44@Deprecated 45public class SimpleTaglet extends BaseTaglet implements InheritableTaglet { 46 47 /** 48 * The marker in the location string for excluded tags. 49 */ 50 public static final String EXCLUDED = "x"; 51 52 /** 53 * The marker in the location string for packages. 54 */ 55 public static final String PACKAGE = "p"; 56 57 /** 58 * The marker in the location string for types. 59 */ 60 public static final String TYPE = "t"; 61 62 /** 63 * The marker in the location string for constructors. 64 */ 65 public static final String CONSTRUCTOR = "c"; 66 67 /** 68 * The marker in the location string for fields. 69 */ 70 public static final String FIELD = "f"; 71 72 /** 73 * The marker in the location string for methods. 74 */ 75 public static final String METHOD = "m"; 76 77 /** 78 * The marker in the location string for overview. 79 */ 80 public static final String OVERVIEW = "o"; 81 82 /** 83 * Use in location string when the tag is to 84 * appear in all locations. 85 */ 86 public static final String ALL = "a"; 87 88 /** 89 * The name of this tag. 90 */ 91 protected String tagName; 92 93 /** 94 * The header to output. 95 */ 96 protected String header; 97 98 /** 99 * The possible locations that this tag can appear in. 100 */ 101 protected String locations; 102 103 /** 104 * Construct a <code>SimpleTaglet</code>. 105 * @param tagName the name of this tag 106 * @param header the header to output. 107 * @param locations the possible locations that this tag 108 * can appear in. The <code>String</code> can contain 'p' 109 * for package, 't' for type, 'm' for method, 'c' for constructor 110 * and 'f' for field. 111 */ 112 public SimpleTaglet(String tagName, String header, String locations) { 113 this.tagName = tagName; 114 this.header = header; 115 locations = StringUtils.toLowerCase(locations); 116 if (locations.contains(ALL) && !locations.contains(EXCLUDED)) { 117 this.locations = PACKAGE + TYPE + FIELD + METHOD + CONSTRUCTOR + OVERVIEW; 118 } else { 119 this.locations = locations; 120 } 121 } 122 123 /** 124 * Return the name of this <code>Taglet</code>. 125 */ 126 public String getName() { 127 return tagName; 128 } 129 130 /** 131 * Return true if this <code>SimpleTaglet</code> 132 * is used in constructor documentation. 133 * @return true if this <code>SimpleTaglet</code> 134 * is used in constructor documentation and false 135 * otherwise. 136 */ 137 public boolean inConstructor() { 138 return locations.contains(CONSTRUCTOR) && !locations.contains(EXCLUDED); 139 } 140 141 /** 142 * Return true if this <code>SimpleTaglet</code> 143 * is used in field documentation. 144 * @return true if this <code>SimpleTaglet</code> 145 * is used in field documentation and false 146 * otherwise. 147 */ 148 public boolean inField() { 149 return locations.contains(FIELD) && !locations.contains(EXCLUDED); 150 } 151 152 /** 153 * Return true if this <code>SimpleTaglet</code> 154 * is used in method documentation. 155 * @return true if this <code>SimpleTaglet</code> 156 * is used in method documentation and false 157 * otherwise. 158 */ 159 public boolean inMethod() { 160 return locations.contains(METHOD) && !locations.contains(EXCLUDED); 161 } 162 163 /** 164 * Return true if this <code>SimpleTaglet</code> 165 * is used in overview documentation. 166 * @return true if this <code>SimpleTaglet</code> 167 * is used in overview documentation and false 168 * otherwise. 169 */ 170 public boolean inOverview() { 171 return locations.contains(OVERVIEW) && !locations.contains(EXCLUDED); 172 } 173 174 /** 175 * Return true if this <code>SimpleTaglet</code> 176 * is used in package documentation. 177 * @return true if this <code>SimpleTaglet</code> 178 * is used in package documentation and false 179 * otherwise. 180 */ 181 public boolean inPackage() { 182 return locations.contains(PACKAGE) && !locations.contains(EXCLUDED); 183 } 184 185 /** 186 * Return true if this <code>SimpleTaglet</code> 187 * is used in type documentation (classes or interfaces). 188 * @return true if this <code>SimpleTaglet</code> 189 * is used in type documentation and false 190 * otherwise. 191 */ 192 public boolean inType() { 193 return locations.contains(TYPE) && !locations.contains(EXCLUDED); 194 } 195 196 /** 197 * Return true if this <code>Taglet</code> 198 * is an inline tag. 199 * @return true if this <code>Taglet</code> 200 * is an inline tag and false otherwise. 201 */ 202 public boolean isInlineTag() { 203 return false; 204 } 205 206 @Override 207 public void inherit(DocFinder.Input input, DocFinder.Output output) { 208 Tag[] tags = input.element.tags(tagName); 209 if (tags.length > 0) { 210 output.holder = input.element; 211 output.holderTag = tags[0]; 212 output.inlineTags = input.isFirstSentence 213 ? tags[0].firstSentenceTags() : tags[0].inlineTags(); 214 } 215 } 216 217 /** 218 * {@inheritDoc} 219 */ 220 public Content getTagletOutput(Tag tag, TagletWriter writer) { 221 return header == null || tag == null ? null : writer.simpleTagOutput(tag, header); 222 } 223 224 /** 225 * {@inheritDoc} 226 */ 227 public Content getTagletOutput(Doc holder, TagletWriter writer) { 228 if (header == null || holder.tags(getName()).length == 0) { 229 return null; 230 } 231 return writer.simpleTagOutput(holder.tags(getName()), header); 232 } 233} 234