Taglet.java revision 4151:123eb0956a45 
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 com.sun.tools.doclets;
27
28import com.sun.javadoc.*;
29
30/**
31 * The interface for a custom tag used by Doclets. A custom
32 * tag must implement this interface.
33 *
34 * <p style="font-style: italic; font-size:larger">
35 * <b>Note:</b> This interface has been superseded by its replacement,
36 * {@link jdk.javadoc.doclet.Taglet}.
37 * </p>
38 *
39 * To be loaded and used by
40 * doclets at run-time, the taglet must have a static method called
41 * <code>register</code> that accepts a {@link java.util.Map} as an
42 * argument with the following signature:
43 * <pre>
44 *   public void register(Map map)
45 * </pre>
46 * This method should add an instance of the custom taglet to the map
47 * with the name of the taglet as the key.  If overriding a taglet,
48 * to avoid a name conflict, the overridden taglet must be deleted from
49 * the map before an instance of the new taglet is added to the map.
50 * <p>
51 * It is recommended that the taglet throw an exception when it fails
52 * to register itself.  The exception that it throws is up to the user.
53 * <p>
54 * Here are two sample taglets: <br>
55 * <ul>
56 *  <li><a href="http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/taglet/ToDoTaglet.java">ToDoTaglet.java</a>
57 *         - Standalone taglet</li>
58 *  <li><a href="http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/taglet/UnderlineTaglet.java">UnderlineTaglet.java</a>
59 *         - Inline taglet</li>
60 * </ul>
61 * <p>
62 * For more information on how to create your own Taglets, please see the
63 * <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/taglet/overview.html">Taglet Overview</a>.
64 *
65 * @since 1.4
66 * @author Jamie Ho
67 *
68 * @deprecated
69 * This interface has been superseded by its replacement,
70 * {@link jdk.javadoc.doclet.Taglet}.
71 */
72@Deprecated
73public interface Taglet {
74
75    /**
76     * Return true if this <code>Taglet</code>
77     * is used in field documentation.  Set to
78     * false for inline tags.
79     * @return true if this <code>Taglet</code>
80     * is used in field documentation and false
81     * otherwise.
82     */
83    public abstract boolean inField();
84
85    /**
86     * Return true if this <code>Taglet</code>
87     * is used in constructor documentation. Set to
88     * false for inline tags.
89     * @return true if this <code>Taglet</code>
90     * is used in constructor documentation and false
91     * otherwise.
92     */
93    public abstract boolean inConstructor();
94
95    /**
96     * Return true if this <code>Taglet</code>
97     * is used in method documentation. Set to
98     * false for inline tags.
99     * @return true if this <code>Taglet</code>
100     * is used in method documentation and false
101     * otherwise.
102     */
103    public abstract boolean inMethod();
104
105    /**
106     * Return true if this <code>Taglet</code>
107     * is used in overview documentation. Set to
108     * false for inline tags.
109     * @return true if this <code>Taglet</code>
110     * is used in method documentation and false
111     * otherwise.
112     */
113    public abstract boolean inOverview();
114
115    /**
116     * Return true if this <code>Taglet</code>
117     * is used in package documentation. Set to
118     * false for inline tags.
119     * @return true if this <code>Taglet</code>
120     * is used in package documentation and false
121     * otherwise.
122     */
123    public abstract boolean inPackage();
124
125    /**
126     * Return true if this <code>Taglet</code>
127     * is used in type documentation (classes or
128     * interfaces). Set to false for inline tags.
129     * @return true if this <code>Taglet</code>
130     * is used in type documentation and false
131     * otherwise.
132     */
133    public abstract boolean inType();
134
135    /**
136     * Return true if this <code>Taglet</code>
137     * is an inline tag. Return false otherwise.
138     * @return true if this <code>Taglet</code>
139     * is an inline tag and false otherwise.
140     */
141    public abstract boolean isInlineTag();
142
143    /**
144     * Return the name of this custom tag.
145     * @return the name of this custom tag.
146     */
147    public abstract String getName();
148
149    /**
150     * Given the <code>Tag</code> representation of this custom
151     * tag, return its string representation, which is output
152     * to the generated page.
153     * @param tag the <code>Tag</code> representation of this custom tag.
154     * @return the string representation of this <code>Tag</code>.
155     */
156    public abstract String toString(Tag tag);
157
158    /**
159     * Given an array of <code>Tag</code>s representing this custom
160     * tag, return its string representation, which is output
161     * to the generated page.  This method should
162     * return null if this taglet represents an inline tag.
163     * @param tags the array of <code>Tag</code>s representing of this custom tag.
164     * @return the string representation of this <code>Tag</code>.
165     */
166    public abstract String toString(Tag[] tags);
167
168}
169