34 |
34 |
35 /** |
35 /** |
36 * The interface for a custom taglet supported by doclets such as |
36 * The interface for a custom taglet supported by doclets such as |
37 * the {@link jdk.javadoc.doclet.StandardDoclet standard doclet}. |
37 * the {@link jdk.javadoc.doclet.StandardDoclet standard doclet}. |
38 * Custom taglets are used to handle custom tags in documentation |
38 * Custom taglets are used to handle custom tags in documentation |
39 * comments. |
39 * comments; custom tags can be either <i>block tags</i>, which |
|
40 * appear at the end of a comment, or <i>inline tags</i>, which |
|
41 * can appear within the main body of a documentation comment. |
40 * |
42 * |
41 * <p>A custom taglet must implement this interface, and must have |
43 * <p> Each implementation of a taglet must provide a public no-argument constructor |
42 * a public default constructor (i.e. a public constructor with no |
44 * to be used by doclets to instantiate the taglet. A doclet will interact |
43 * parameters), by which, the doclet will instantiate and |
45 * with classes implementing this interface as follows: |
44 * register the custom taglet. |
|
45 * |
46 * |
|
47 * <ol> |
|
48 * <li> The doclet will create an instance of a taglet using the no-arg |
|
49 * constructor of the taglet class. |
|
50 * <li> Next, the doclet calls the {@link #init(DocletEnvironment,Doclet) init} |
|
51 method with an appropriate environment and doclet. |
|
52 * <li> Afterwards, the doclet calls {@link #getName() getName}, |
|
53 * {@link #getAllowedLocations() getAllowedLocations}, and |
|
54 * {@link #isInlineTag() isInlineTag}, to determine the characteristics |
|
55 * of the tags supported by the taglet. |
|
56 * <li> As appropriate, the doclet calls the |
|
57 * {@link #toString(List,Element) toString} method on the taglet object, |
|
58 * giving it a list of tags and the element for which the tags are part |
|
59 * of the element's documentation comment, from which the taglet can |
|
60 * determine the string to be included in the documentation. |
|
61 * The doclet will typically specify any requirements on the contents of |
|
62 * the string that is returned. |
|
63 * </ol> |
|
64 * |
|
65 * <p>If a taglet object is created and used without the above protocol being |
|
66 * followed, then the taglet's behavior is not defined by this interface |
|
67 * specification. |
|
68 * |
|
69 * @apiNote |
|
70 * It is typical for a taglet to be designed to work in conjunction with a |
|
71 * specific doclet. |
|
72 * |
|
73 * @see <a href="StandardDoclet.html#user-defined-taglets">User-Defined Taglets |
|
74 * for the Standard Doclet</a> |
46 * @since 9 |
75 * @since 9 |
47 */ |
76 */ |
48 |
77 |
49 public interface Taglet { |
78 public interface Taglet { |
50 |
79 |
83 default void init(DocletEnvironment env, Doclet doclet) { } |
112 default void init(DocletEnvironment env, Doclet doclet) { } |
84 |
113 |
85 /** |
114 /** |
86 * Returns the string representation of a series of instances of |
115 * Returns the string representation of a series of instances of |
87 * this tag to be included in the generated output. |
116 * this tag to be included in the generated output. |
88 * If this taglet is for an {@link #isInlineTag inline} tag it will |
117 * |
|
118 * <p>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. |
119 * 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 |
120 * 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. |
121 * comment, with a list of all the instances of the tag in a comment. |
|
122 * |
92 * @param tags the list of instances of this tag |
123 * @param tags the list of instances of this tag |
93 * @param element the element to which the enclosing comment belongs |
124 * @param element the element to which the enclosing comment belongs |
94 * @return the string representation of the tags to be included in |
125 * @return the string representation of the tags to be included in |
95 * the generated output |
126 * the generated output |
|
127 * |
|
128 * @see <a href="StandardDoclet.html#user-defined-taglets">User-Defined Taglets |
|
129 * for the Standard Doclet</a> |
96 */ |
130 */ |
97 String toString(List<? extends DocTree> tags, Element element); |
131 String toString(List<? extends DocTree> tags, Element element); |
98 |
132 |
99 /** |
133 /** |
100 * The kind of location in which a tag may be used. |
134 * The kind of location in which a tag may be used. |