1 /* 2 * Copyright (c) 2001, 2019, 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.doclet; 27 28 import java.util.List; 29 import java.util.Set; 30 31 import javax.lang.model.element.Element; 32 33 import com.sun.source.doctree.DocTree; 34 35 /** 36 * The interface for a custom taglet supported by doclets such as 37 * the {@link jdk.javadoc.doclet.StandardDoclet standard doclet}. 38 * Custom taglets are used to handle custom tags in documentation 39 * comments; custom tags can be instantiated individually as either 40 * <i>block tags</i>, which appear at the end of a comment, 41 * or <i>inline tags</i>, which can appear within the main body of a 42 * documentation comment. 43 * 44 * <p> Each implementation of a taglet must provide a public no-argument constructor 45 * to be used by doclets to instantiate the taglet. A doclet will interact 46 * with classes implementing this interface as follows: 47 * 48 * <ol> 49 * <li> The doclet will create an instance of a taglet using the no-arg 50 * constructor of the taglet class. 51 * <li> Next, the doclet calls the {@link #init(DocletEnvironment,Doclet) init} 52 method with an appropriate environment and doclet. 53 * <li> Afterwards, the doclet calls {@link #getName() getName}, 54 * {@link #getAllowedLocations() getAllowedLocations}, and 55 * {@link #isInlineTag() isInlineTag}, to determine the characteristics 56 * of the tags supported by the taglet. 57 * <li> As appropriate, the doclet calls the 58 * {@link #toString(List,Element) toString} method on the taglet object, 59 * giving it a list of tags and the element for which the tags are part 60 * of the element's documentation comment, from which the taglet can 61 * determine the string to be included in the documentation. 62 * The doclet will typically specify any requirements on the contents of 63 * the string that is returned. 64 * </ol> 65 * 66 * <p>If a taglet object is created and used without the above protocol being 67 * followed, then the taglet's behavior is not defined by this interface 68 * specification. 69 * 70 * @apiNote 71 * It is typical for a taglet to be designed to work in conjunction with a 72 * specific doclet. 73 * 74 * @see <a href="StandardDoclet.html#user-defined-taglets">User-Defined Taglets 75 * for the Standard Doclet</a> 76 * @since 9 77 */ 78 79 public interface Taglet { 80 81 /** 82 * Returns the set of supported locations for block tags. 83 * @return the set of supported locations for block tags 84 */ getAllowedLocations()85 Set<Location> getAllowedLocations(); 86 87 /** 88 * Indicates whether this taglet supports inline tags. 89 * 90 * @return true if this taglet supports inline tags 91 */ isInlineTag()92 boolean isInlineTag(); 93 94 /** 95 * Indicates whether this taglet supports block tags. 96 * 97 * @return true if this taglet supports block tags 98 * @implSpec This implementation returns the inverse 99 * result to {@code isInlineTag}. 100 */ isBlockTag()101 default boolean isBlockTag() { 102 return !isInlineTag(); 103 } 104 105 /** 106 * Returns the name of the tag supported by this taglet. 107 * @return the name of this tag 108 */ getName()109 String getName(); 110 111 /** 112 * Initializes this taglet with the given doclet environment and doclet. 113 * 114 * @apiNote 115 * The environment may be used to access utility classes for 116 * {@link javax.lang.model.util.Elements elements} and 117 * {@link javax.lang.model.util.Types types} if needed. 118 * 119 * @implSpec 120 * This implementation does nothing. 121 * 122 * @param env the environment in which the doclet and taglet are running 123 * @param doclet the doclet that instantiated this taglet 124 */ init(DocletEnvironment env, Doclet doclet)125 default void init(DocletEnvironment env, Doclet doclet) { } 126 127 /** 128 * Returns the string representation of a series of instances of 129 * this tag to be included in the generated output. 130 * 131 * <p>If this taglet supports {@link #isInlineTag inline} tags, it will 132 * be called once per instance of the inline tag, each time with a singleton list. 133 * If this taglet supports {@link #isBlockTag block} tags, it will be called once 134 * for each comment containing instances of block tags, with a list of all the instances 135 * of the block tag in that comment. 136 * 137 * @param tags the list of instances of this tag 138 * @param element the element to which the enclosing comment belongs 139 * @return the string representation of the tags to be included in 140 * the generated output 141 * 142 * @see <a href="StandardDoclet.html#user-defined-taglets">User-Defined Taglets 143 * for the Standard Doclet</a> 144 */ toString(List<? extends DocTree> tags, Element element)145 String toString(List<? extends DocTree> tags, Element element); 146 147 /** 148 * The kind of location in which a tag may be used. 149 */ 150 enum Location { 151 /** In an Overview document. */ 152 OVERVIEW, 153 /** In the documentation for a module. */ 154 MODULE, 155 /** In the documentation for a package. */ 156 PACKAGE, 157 /** In the documentation for a type, such as a class, interface or enum. */ 158 TYPE, 159 /** In the documentation for a constructor. */ 160 CONSTRUCTOR, 161 /** In the documentation for a method. */ 162 METHOD, 163 /** In the documentation for a field. */ 164 FIELD 165 } 166 } 167