DocTree.java revision 2571:10fc81ac75b4 
1/*
2 * Copyright (c) 2011, 2014, 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 {@link InheritDocTree}
114         * representing an @inheritDoc tag.
115         */
116        INHERIT_DOC("inheritDoc"),
117
118        /**
119         * Used for instances of {@link LinkTree}
120         * representing an @link tag.
121         */
122        LINK("link"),
123
124        /**
125         * Used for instances of {@link LinkTree}
126         * representing an @linkplain tag.
127         */
128        LINK_PLAIN("linkplain"),
129
130        /**
131         * Used for instances of {@link LiteralTree}
132         * representing an @literal tag.
133         */
134        LITERAL("literal"),
135
136        /**
137         * Used for instances of {@link ParamTree}
138         * representing an @param tag.
139         */
140        PARAM("param"),
141
142        /**
143         * Used for instances of {@link ReferenceTree}
144         * representing a reference to a element in the
145         * Java programming language.
146         */
147        REFERENCE,
148
149        /**
150         * Used for instances of {@link ReturnTree}
151         * representing an @return tag.
152         */
153        RETURN("return"),
154
155        /**
156         * Used for instances of {@link SeeTree}
157         * representing an @see tag.
158         */
159        SEE("see"),
160
161        /**
162         * Used for instances of {@link SerialTree}
163         * representing an @serial tag.
164         */
165        SERIAL("serial"),
166
167        /**
168         * Used for instances of {@link SerialDataTree}
169         * representing an @serialData tag.
170         */
171        SERIAL_DATA("serialData"),
172
173        /**
174         * Used for instances of {@link SerialFieldTree}
175         * representing an @serialField tag.
176         */
177        SERIAL_FIELD("serialField"),
178
179        /**
180         * Used for instances of {@link SinceTree}
181         * representing an @since tag.
182         */
183        SINCE("since"),
184
185        /**
186         * Used for instances of {@link EndElementTree}
187         * representing the start of an HTML element.
188         */
189        START_ELEMENT,
190
191        /**
192         * Used for instances of {@link TextTree}
193         * representing some documentation text.
194         */
195        TEXT,
196
197        /**
198         * Used for instances of {@link ThrowsTree}
199         * representing an @throws tag.
200         */
201        THROWS("throws"),
202
203        /**
204         * Used for instances of {@link UnknownBlockTagTree}
205         * representing an unknown block tag.
206         */
207        UNKNOWN_BLOCK_TAG,
208
209        /**
210         * Used for instances of {@link UnknownInlineTagTree}
211         * representing an unknown inline tag.
212         */
213        UNKNOWN_INLINE_TAG,
214
215        /**
216         * Used for instances of {@link ValueTree}
217         * representing an @value tag.
218         */
219        VALUE("value"),
220
221        /**
222         * Used for instances of {@link VersionTree}
223         * representing an @version tag.
224         */
225        VERSION("version"),
226
227        /**
228         * An implementation-reserved node. This is the not the node
229         * you are looking for.
230         */
231        OTHER;
232
233        /**
234         * The name of the tag, if any, associated with this kind of node.
235         */
236        public final String tagName;
237
238        Kind() {
239            tagName = null;
240        }
241
242        Kind(String tagName) {
243            this.tagName = tagName;
244        }
245    }
246
247    /**
248     * Returns the kind of this tree.
249     *
250     * @return the kind of this tree.
251     */
252    Kind getKind();
253
254    /**
255     * Accept method used to implement the visitor pattern.  The
256     * visitor pattern is used to implement operations on trees.
257     *
258     * @param <R> result type of this operation.
259     * @param <D> type of additional data.
260     * @param visitor the visitor to be called
261     * @param data a parameter value to be passed to the visitor method
262     * @return the value returned from the visitor method
263     */
264    <R, D> R accept(DocTreeVisitor<R,D> visitor, D data);
265}
266