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