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          * 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 DocTypeTree}
  82          * representing an HTML DocType declaration.
  83          */
  84         DOC_TYPE,
  85 
  86         /**
  87          * Used for instances of {@link EndElementTree}
  88          * representing the end of an HTML element.
  89          */
  90         END_ELEMENT,
  91 
  92         /**
  93          * Used for instances of {@link EntityTree}
  94          * representing an HTML entity.
  95          */
  96         ENTITY,
  97 
  98         /**
  99          * Used for instances of {@link ErroneousTree}
 100          * representing some invalid text.
 101          */
 102         ERRONEOUS,
 103 
 104         /**
 105          * Used for instances of {@link ThrowsTree}
 106          * representing an @exception tag.
 107          */
 108         EXCEPTION("exception"),
 109 
 110         /**
 111          * Used for instances of {@link HiddenTree}
 112          * representing an @hidden tag.
 113          */
 114         HIDDEN("hidden"),
 115 
 116         /**
 117          * Used for instances of {@link IdentifierTree}
 118          * representing an identifier.
 119          */
 120         IDENTIFIER,
 121 
 122         /**
 123          * Used for instances of {@link IndexTree}
 124          * representing a search term.
 125          */
 126         INDEX("index"),
 127 
 128         /**
 129          * Used for instances of {@link InheritDocTree}
 130          * representing an @inheritDoc tag.
 131          */
 132         INHERIT_DOC("inheritDoc"),
 133 
 134         /**
 135          * Used for instances of {@link LinkTree}
 136          * representing an @link tag.
 137          */
 138         LINK("link"),
 139 
 140         /**
 141          * Used for instances of {@link LinkTree}
 142          * representing an @linkplain tag.
 143          */
 144         LINK_PLAIN("linkplain"),
 145 
 146         /**
 147          * Used for instances of {@link LiteralTree}
 148          * representing an @literal tag.
 149          */
 150         LITERAL("literal"),
 151 
 152         /**
 153          * Used for instances of {@link ParamTree}
 154          * representing an @param tag.
 155          */
 156         PARAM("param"),
 157 
 158         /**
 159          * Used for instances of {@link ProvidesTree}
 160          * representing an @provides tag.
 161          */
 162         PROVIDES("provides"),
 163 
 164         /**
 165          * Used for instances of {@link ReferenceTree}
 166          * representing a reference to a element in the
 167          * Java programming language.
 168          */
 169         REFERENCE,
 170 
 171         /**
 172          * Used for instances of {@link ReturnTree}
 173          * representing an @return tag.
 174          */
 175         RETURN("return"),
 176 
 177         /**
 178          * Used for instances of {@link SeeTree}
 179          * representing an @see tag.
 180          */
 181         SEE("see"),
 182 
 183         /**
 184          * Used for instances of {@link SerialTree}
 185          * representing an @serial tag.
 186          */
 187         SERIAL("serial"),
 188 
 189         /**
 190          * Used for instances of {@link SerialDataTree}
 191          * representing an @serialData tag.
 192          */
 193         SERIAL_DATA("serialData"),
 194 
 195         /**
 196          * Used for instances of {@link SerialFieldTree}
 197          * representing an @serialField tag.
 198          */
 199         SERIAL_FIELD("serialField"),
 200 
 201         /**
 202          * Used for instances of {@link SinceTree}
 203          * representing an @since tag.
 204          */
 205         SINCE("since"),
 206 
 207         /**
 208          * Used for instances of {@link EndElementTree}
 209          * representing the start of an HTML element.
 210          */
 211         START_ELEMENT,
 212 
 213         /**
 214          * Used for instances of {@link SystemPropertyTree}
 215          * representing an @systemProperty tag.
 216          */
 217         SYSTEM_PROPERTY("systemProperty"),
 218 
 219         /**
 220          * Used for instances of {@link SummaryTree}
 221          * representing the summary of a comment description.
 222          */
 223         SUMMARY("summary"),
 224 
 225         /**
 226          * Used for instances of {@link TextTree}
 227          * representing some documentation text.
 228          */
 229         TEXT,
 230 
 231         /**
 232          * Used for instances of {@link ThrowsTree}
 233          * representing an @throws tag.
 234          */
 235         THROWS("throws"),
 236 
 237         /**
 238          * Used for instances of {@link UnknownBlockTagTree}
 239          * representing an unknown block tag.
 240          */
 241         UNKNOWN_BLOCK_TAG,
 242 
 243         /**
 244          * Used for instances of {@link UnknownInlineTagTree}
 245          * representing an unknown inline tag.
 246          */
 247         UNKNOWN_INLINE_TAG,
 248 
 249         /**
 250          * Used for instances of {@link UsesTree}
 251          * representing an @uses tag.
 252          */
 253         USES("uses"),
 254 
 255         /**
 256          * Used for instances of {@link ValueTree}
 257          * representing an @value tag.
 258          */
 259         VALUE("value"),
 260 
 261         /**
 262          * Used for instances of {@link VersionTree}
 263          * representing an @version tag.
 264          */
 265         VERSION("version"),
 266 
 267         /**
 268          * An implementation-reserved node. This is the not the node
 269          * you are looking for.
 270          */
 271         OTHER;
 272 
 273         /**
 274          * The name of the tag, if any, associated with this kind of node.
 275          */
 276         public final String tagName;
 277 
 278         Kind() {
 279             tagName = null;
 280         }
 281 
 282         Kind(String tagName) {
 283             this.tagName = tagName;
 284         }
 285     }
 286 
 287     /**
 288      * Returns the kind of this tree.
 289      *
 290      * @return the kind of this tree.
 291      */
 292     Kind getKind();
 293 
 294     /**
 295      * Accept method used to implement the visitor pattern.  The
 296      * visitor pattern is used to implement operations on trees.
 297      *
 298      * @param <R> result type of this operation.
 299      * @param <D> type of additional data.
 300      * @param visitor the visitor to be called
 301      * @param data a parameter value to be passed to the visitor method
 302      * @return the value returned from the visitor method
 303      */
 304     <R, D> R accept(DocTreeVisitor<R,D> visitor, D data);
 305 }