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 

    26 package jdk.javadoc.doclet;

    27 

    28 import java.util.List;

    29 import java.util.Set;

    30 

    31 import com.sun.source.doctree.DocTree;

    32 

    33 /**

    34  * The interface for a custom taglet supported by doclets such as

    35  * the {@link jdk.javadoc.doclet.StandardDoclet standard doclet}.

    36  * Custom taglets are used to handle custom tags in documentation

    37  * comments.

    38  *

    39  * <p>A custom taglet must implement this interface, and must have

    40  * a public default constructor (i.e. a public constructor with no

    41  * parameters), by which, the doclet will instantiate and

    42  * register the custom taglet.

    43  *

    44  * @since 9

    45  */

    46 

    47 public interface Taglet {

    48 

    49     /**

    50      * Returns the set of locations in which a tag may be used.

    51      * @return the set of locations in which a tag may be used

    52      */

    53     Set<Location> getAllowedLocations();

    54 

    55     /**

    56      * Indicates whether this taglet is for inline tags or not.

    57      * @return true if this taglet is for an inline tag, and false otherwise

    58      */

    59     boolean isInlineTag();

    60 

    61     /**

    62      * Returns the name of the tag.

    63      * @return the name of this custom tag.

    64      */

    65     String getName();

    66 

    67     /**

    68      * Returns the string representation of a series of instances of

    69      * this tag to be included in the generated output.

    70      * If this taglet is for an {@link #isInlineTag inline} tag} it will

    71      * be called once per instance of the tag, each time with a singleton list.

    72      * Otherwise, if this tag is a block tag, it will be called once per

    73      * comment, with a list of all the instances of the tag in the comment.

    74      * @param tags the list of {@code DocTree} containing one or more

    75      *  instances of this tag

    76      * @return the string representation of the tags to be included in

    77      *  the generated output

    78      */

    79     String toString(List<? extends DocTree> tags);

    80 

    81     /**

    82      * The kind of location in which a tag may be used.

    83      */

    84     public static enum Location {

    85         /** In an Overview document. */

    86         OVERVIEW,

    87         /** In the documentation for a module. */

    88         MODULE,

    89         /** In the documentation for a package. */

    90         PACKAGE,

    91         /** In the documentation for a class, interface or enum. */

    92         TYPE,

    93         /** In the documentation for a constructor. */

    94         CONSTRUCTOR,

    95         /** In the documentation for a method. */

    96         METHOD,

    97         /** In the documentation for a field. */

    98         FIELD

    99     }

   100 }