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