jdk8-mips64-public/langtools: src/share/classes/com/sun/source/util/DocSourcePositions.java@2eb010b6cb22

     1 /*

     2  * Copyright (c) 2013, 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  */

    26 package com.sun.source.util;

    28 import com.sun.source.doctree.DocCommentTree;

    29 import com.sun.source.doctree.DocTree;

    30 import com.sun.source.tree.CompilationUnitTree;

    32 /**

    33  * Provides methods to obtain the position of a DocTree within a javadoc comment.

    34  * A position is defined as a simple character offset from the start of a

    35  * CompilationUnit where the first character is at offset 0.

    36  *

    37  * @since 1.8

    38  */

    39 @jdk.Exported

    40 public interface DocSourcePositions extends SourcePositions {

    42     /**

    43      * Gets the starting position of the tree within the comment within the file.  If tree is not found within

    44      * file, or if the starting position is not available,

    45      * return {@link javax.tools.Diagnostic#NOPOS}.

    46      * The given tree should be under the given comment tree, and the given documentation

    47      * comment tree should be returned from a {@link DocTrees#getDocCommentTree(com.sun.source.util.TreePath) }

    48      * for a tree under the given file.

    49      * The returned position must be at the start of the yield of this tree, that

    50      * is for any sub-tree of this tree, the following must hold:

    51      *

    52      * <p>

    53      * {@code tree.getStartPosition() <= subtree.getStartPosition()} or <br>

    54      * {@code tree.getStartPosition() == NOPOS} or <br>

    55      * {@code subtree.getStartPosition() == NOPOS}

    56      * </p>

    57      *

    58      * @param file CompilationUnit in which to find tree.

    59      * @param comment the comment tree that encloses the tree for which the

    60      *                position is being sought

    61      * @param tree tree for which a position is sought.

    62      * @return the start position of tree.

    63      */

    64     long getStartPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree);

    66     /**

    67      * Gets the ending position of the tree within the comment within the file.  If tree is not found within

    68      * file, or if the ending position is not available,

    69      * return {@link javax.tools.Diagnostic#NOPOS}.

    70      * The given tree should be under the given comment tree, and the given documentation

    71      * comment tree should be returned from a {@link DocTrees#getDocCommentTree(com.sun.source.util.TreePath) }

    72      * for a tree under the given file.

    73      * The returned position must be at the end of the yield of this tree,

    74      * that is for any sub-tree of this tree, the following must hold:

    75      *

    76      * <p>

    77      * {@code tree.getEndPosition() >= subtree.getEndPosition()} or <br>

    78      * {@code tree.getEndPosition() == NOPOS} or <br>

    79      * {@code subtree.getEndPosition() == NOPOS}

    80      * </p>

    81      *

    82      * In addition, the following must hold:

    83      *

    84      * <p>

    85      * {@code tree.getStartPosition() <= tree.getEndPosition()}  or <br>

    86      * {@code tree.getStartPosition() == NOPOS} or <br>

    87      * {@code tree.getEndPosition() == NOPOS}

    88      * </p>

    89      *

    90      * @param file CompilationUnit in which to find tree.

    91      * @param comment the comment tree that encloses the tree for which the

    92      *                position is being sought

    93      * @param tree tree for which a position is sought.

    94      * @return the start position of tree.

    95      */

    96     long getEndPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree);

    98 }

Mercurial > jdk8-mips64-public > langtools / file revision