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 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 SummaryTree}

   209          * representing the summary of a comment description.

   210          */

   211         SUMMARY("summary"),

   212 

   213         /**

   214          * Used for instances of {@link TextTree}

   215          * representing some documentation text.

   216          */

   217         TEXT,

   218 

   219         /**

   220          * Used for instances of {@link ThrowsTree}

   221          * representing an @throws tag.

   222          */

   223         THROWS("throws"),

   224 

   225         /**

   226          * Used for instances of {@link UnknownBlockTagTree}

   227          * representing an unknown block tag.

   228          */

   229         UNKNOWN_BLOCK_TAG,

   230 

   231         /**

   232          * Used for instances of {@link UnknownInlineTagTree}

   233          * representing an unknown inline tag.

   234          */

   235         UNKNOWN_INLINE_TAG,

   236 

   237         /**

   238          * Used for instances of {@link UsesTree}

   239          * representing an @uses tag.

   240          */

   241         USES("uses"),

   242 

   243         /**

   244          * Used for instances of {@link ValueTree}

   245          * representing an @value tag.

   246          */

   247         VALUE("value"),

   248 

   249         /**

   250          * Used for instances of {@link VersionTree}

   251          * representing an @version tag.

   252          */

   253         VERSION("version"),

   254 

   255         /**

   256          * An implementation-reserved node. This is the not the node

   257          * you are looking for.

   258          */

   259         OTHER;

   260 

   261         /**

   262          * The name of the tag, if any, associated with this kind of node.

   263          */

   264         public final String tagName;

   265 

   266         Kind() {

   267             tagName = null;

   268         }

   269 

   270         Kind(String tagName) {

   271             this.tagName = tagName;

   272         }

   273     }

   274 

   275     /**

   276      * Returns the kind of this tree.

   277      *

   278      * @return the kind of this tree.

   279      */

   280     Kind getKind();

   281 

   282     /**

   283      * Accept method used to implement the visitor pattern.  The

   284      * visitor pattern is used to implement operations on trees.

   285      *

   286      * @param <R> result type of this operation.

   287      * @param <D> type of additional data.

   288      * @param visitor the visitor to be called

   289      * @param data a parameter value to be passed to the visitor method

   290      * @return the value returned from the visitor method

   291      */

   292     <R, D> R accept(DocTreeVisitor<R,D> visitor, D data);

   293 }