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