DocTree.java revision 3831:209b0eab0e1f 
1/*
2 * Copyright (c) 2011, 2016, 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.source.doctree;
27
28/**
29 * Common interface for all nodes in a documentation syntax tree.
30 *
31 * @since 1.8
32 */
33public interface DocTree {
34    /**
35     * Enumerates all kinds of trees.
36     */
37    enum Kind {
38        /**
39         * Used for instances of {@link AttributeTree}
40         * representing an HTML attribute.
41         */
42        ATTRIBUTE,
43
44        /**
45         * Used for instances of {@link AuthorTree}
46         * representing an @author tag.
47         */
48        AUTHOR("author"),
49
50        /**
51         * Used for instances of {@link LiteralTree}
52         * representing an @code tag.
53         */
54        CODE("code"),
55
56        /**
57         * Used for instances of {@link CommentTree}
58         * representing an HTML comment.
59         */
60        COMMENT,
61
62        /**
63         * Used for instances of {@link DeprecatedTree}
64         * representing an @deprecated tag.
65         */
66        DEPRECATED("deprecated"),
67
68        /**
69         * Used for instances of {@link DocCommentTree}
70         * representing a complete doc comment.
71         */
72        DOC_COMMENT,
73
74        /**
75         * Used for instances of {@link DocRootTree}
76         * representing an @docRoot tag.
77         */
78        DOC_ROOT("docRoot"),
79
80        /**
81         * Used for instances of {@link EndElementTree}
82         * representing the end of an HTML element.
83         */
84        END_ELEMENT,
85
86        /**
87         * Used for instances of {@link EntityTree}
88         * representing an HTML entity.
89         */
90        ENTITY,
91
92        /**
93         * Used for instances of {@link ErroneousTree}
94         * representing some invalid text.
95         */
96        ERRONEOUS,
97
98        /**
99         * Used for instances of {@link ThrowsTree}
100         * representing an @exception tag.
101         */
102        EXCEPTION("exception"),
103
104        /**
105         * Used for instances of {@link HiddenTree}
106         * representing an @hidden tag.
107         */
108        HIDDEN("hidden"),
109
110        /**
111         * Used for instances of {@link IdentifierTree}
112         * representing an identifier.
113         */
114        IDENTIFIER,
115
116        /**
117         * Used for instances of {@link IndexTree}
118         * representing a search term.
119         */
120        INDEX("index"),
121
122        /**
123         * Used for instances of {@link InheritDocTree}
124         * representing an @inheritDoc tag.
125         */
126        INHERIT_DOC("inheritDoc"),
127
128        /**
129         * Used for instances of {@link LinkTree}
130         * representing an @link tag.
131         */
132        LINK("link"),
133
134        /**
135         * Used for instances of {@link LinkTree}
136         * representing an @linkplain tag.
137         */
138        LINK_PLAIN("linkplain"),
139
140        /**
141         * Used for instances of {@link LiteralTree}
142         * representing an @literal tag.
143         */
144        LITERAL("literal"),
145
146        /**
147         * Used for instances of {@link ParamTree}
148         * representing an @param tag.
149         */
150        PARAM("param"),
151
152        /**
153         * Used for instances of {@link ProvidesTree}
154         * representing an @provides tag.
155         */
156        PROVIDES("provides"),
157
158        /**
159         * Used for instances of {@link ReferenceTree}
160         * representing a reference to a element in the
161         * Java programming language.
162         */
163        REFERENCE,
164
165        /**
166         * Used for instances of {@link ReturnTree}
167         * representing an @return tag.
168         */
169        RETURN("return"),
170
171        /**
172         * Used for instances of {@link SeeTree}
173         * representing an @see tag.
174         */
175        SEE("see"),
176
177        /**
178         * Used for instances of {@link SerialTree}
179         * representing an @serial tag.
180         */
181        SERIAL("serial"),
182
183        /**
184         * Used for instances of {@link SerialDataTree}
185         * representing an @serialData tag.
186         */
187        SERIAL_DATA("serialData"),
188
189        /**
190         * Used for instances of {@link SerialFieldTree}
191         * representing an @serialField tag.
192         */
193        SERIAL_FIELD("serialField"),
194
195        /**
196         * Used for instances of {@link SinceTree}
197         * representing an @since tag.
198         */
199        SINCE("since"),
200
201        /**
202         * Used for instances of {@link EndElementTree}
203         * representing the start of an HTML element.
204         */
205        START_ELEMENT,
206
207        /**
208         * Used for instances of {@link TextTree}
209         * representing some documentation text.
210         */
211        TEXT,
212
213        /**
214         * Used for instances of {@link ThrowsTree}
215         * representing an @throws tag.
216         */
217        THROWS("throws"),
218
219        /**
220         * Used for instances of {@link UnknownBlockTagTree}
221         * representing an unknown block tag.
222         */
223        UNKNOWN_BLOCK_TAG,
224
225        /**
226         * Used for instances of {@link UnknownInlineTagTree}
227         * representing an unknown inline tag.
228         */
229        UNKNOWN_INLINE_TAG,
230
231        /**
232         * Used for instances of {@link UsesTree}
233         * representing an @uses tag.
234         */
235        USES("uses"),
236
237        /**
238         * Used for instances of {@link ValueTree}
239         * representing an @value tag.
240         */
241        VALUE("value"),
242
243        /**
244         * Used for instances of {@link VersionTree}
245         * representing an @version tag.
246         */
247        VERSION("version"),
248
249        /**
250         * An implementation-reserved node. This is the not the node
251         * you are looking for.
252         */
253        OTHER;
254
255        /**
256         * The name of the tag, if any, associated with this kind of node.
257         */
258        public final String tagName;
259
260        Kind() {
261            tagName = null;
262        }
263
264        Kind(String tagName) {
265            this.tagName = tagName;
266        }
267    }
268
269    /**
270     * Returns the kind of this tree.
271     *
272     * @return the kind of this tree.
273     */
274    Kind getKind();
275
276    /**
277     * Accept method used to implement the visitor pattern.  The
278     * visitor pattern is used to implement operations on trees.
279     *
280     * @param <R> result type of this operation.
281     * @param <D> type of additional data.
282     * @param visitor the visitor to be called
283     * @param data a parameter value to be passed to the visitor method
284     * @return the value returned from the visitor method
285     */
286    <R, D> R accept(DocTreeVisitor<R,D> visitor, D data);
287}
288