1/* 2 * Copyright (c) 2001, 2017, 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.doclet; 27 28import java.util.List; 29import java.util.Set; 30 31import javax.lang.model.element.Element; 32 33import 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. 40 * 41 * <p>A custom taglet must implement this interface, and must have 42 * a public default constructor (i.e. a public constructor with no 43 * parameters), by which, the doclet will instantiate and 44 * register the custom taglet. 45 * 46 * @since 9 47 */ 48 49public interface Taglet { 50 51 /** 52 * Returns the set of locations in which a tag may be used. 53 * @return the set of locations in which a tag may be used 54 */ 55 Set<Location> getAllowedLocations(); 56 57 /** 58 * Indicates whether this taglet is for inline tags or not. 59 * @return true if this taglet is for an inline tag, and false otherwise 60 */ 61 boolean isInlineTag(); 62 63 /** 64 * Returns the name of the tag. 65 * @return the name of this custom tag. 66 */ 67 String getName(); 68 69 /** 70 * Initializes this taglet with the given doclet environment and doclet. 71 * 72 * @apiNote 73 * The environment may be used to access utility classes for 74 * {@link javax.lang.model.util.Elements elements} and 75 * {@link javax.lang.model.util.Types types} if needed. 76 * 77 * @implSpec 78 * This implementation does nothing. 79 * 80 * @param env the environment in which the doclet and taglet are running 81 * @param doclet the doclet that instantiated this taglet 82 */ 83 default void init(DocletEnvironment env, Doclet doclet) { } 84 85 /** 86 * Returns the string representation of a series of instances of 87 * this tag to be included in the generated output. 88 * If this taglet is for an {@link #isInlineTag inline} tag it will 89 * be called once per instance of the tag, each time with a singleton list. 90 * Otherwise, if this tag is a block tag, it will be called once per 91 * comment, with a list of all the instances of the tag in a comment. 92 * @param tags the list of instances of this tag 93 * @param element the element to which the enclosing comment belongs 94 * @return the string representation of the tags to be included in 95 * the generated output 96 */ 97 String toString(List<? extends DocTree> tags, Element element); 98 99 /** 100 * The kind of location in which a tag may be used. 101 */ 102 public static enum Location { 103 /** In an Overview document. */ 104 OVERVIEW, 105 /** In the documentation for a module. */ 106 MODULE, 107 /** In the documentation for a package. */ 108 PACKAGE, 109 /** In the documentation for a class, interface or enum. */ 110 TYPE, 111 /** In the documentation for a constructor. */ 112 CONSTRUCTOR, 113 /** In the documentation for a method. */ 114 METHOD, 115 /** In the documentation for a field. */ 116 FIELD 117 } 118} 119