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