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