Module jdk.compiler
Package com.sun.source.util

Class DocTrees

  • public abstract class DocTrees
extends Trees
    Provides access to syntax trees for doc comments.
    Since:
    1.8

    • Constructor Detail

      • DocTrees

        public DocTrees()

    • Method Detail

      • instance

        public static DocTrees instance​(JavaCompiler.CompilationTask task)
        Returns a DocTrees object for a given CompilationTask.
        Parameters:
        task - the compilation task for which to get the Trees object
        Returns:
        the DocTrees object
        Throws:
        IllegalArgumentException - if the task does not support the Trees API.

      • instance

        public static DocTrees instance​(ProcessingEnvironment env)
        Returns a DocTrees object for a given ProcessingEnvironment.
        Parameters:
        env - the processing environment for which to get the Trees object
        Returns:
        the DocTrees object
        Throws:
        IllegalArgumentException - if the env does not support the Trees API.

      • getBreakIterator

        public abstract BreakIterator getBreakIterator()
        Returns the break iterator used to compute the first sentence of documentation comments. Returns null if none has been specified.
        Returns:
        the break iterator
        Since:
        9

      • getDocCommentTree

        public abstract DocCommentTree getDocCommentTree​(TreePath path)
        Returns the doc comment tree, if any, for the Tree node identified by a given TreePath. Returns null if no doc comment was found.
        Parameters:
        path - the path for the tree node
        Returns:
        the doc comment tree

      • getDocCommentTree

        public abstract DocCommentTree getDocCommentTree​(Element e)
        Returns the doc comment tree of the given element. Returns null if no doc comment was found.
        Parameters:
        e - an element whose documentation is required
        Returns:
        the doc comment tree
        Since:
        9

      • getDocCommentTree

        public abstract DocCommentTree getDocCommentTree​(FileObject fileObject)
        Returns the doc comment tree of the given file. The file must be an HTML file, in which case the doc comment tree represents the entire contents of the file. Returns null if no doc comment was found. Future releases may support additional file types.
        Parameters:
        fileObject - the content container
        Returns:
        the doc comment tree
        Since:
        9

      • getDocCommentTree

        public abstract DocCommentTree getDocCommentTree​(Element e,
                                                 String relativePath)
                                          throws IOException
        Returns the doc comment tree of the given file whose path is specified relative to the given element. The file must be an HTML file, in which case the doc comment tree represents the contents of the <body> tag, and any enclosing tags are ignored. Returns null if no doc comment was found. Future releases may support additional file types.
        Parameters:
        e - an element whose path is used as a reference
        relativePath - the relative path from the Element
        Returns:
        the doc comment tree
        Throws:
        IOException - if an exception occurs
        Since:
        9

      • getDocTreePath

        public abstract DocTreePath getDocTreePath​(FileObject fileObject,
                                           PackageElement packageElement)
        Returns a doc tree path containing the doc comment tree of the given file. The file must be an HTML file, in which case the doc comment tree represents the contents of the <body> tag, and any enclosing tags are ignored. Any references to source code elements contained in @see and {@link} tags in the doc comment tree will be evaluated in the context of the given package element. Returns null if no doc comment was found.
        Parameters:
        fileObject - a file object encapsulating the HTML content
        packageElement - a package element to associate with the given file object representing a legacy package.html, null otherwise
        Returns:
        a doc tree path containing the doc comment parsed from the given file
        Throws:
        IllegalArgumentException - if the fileObject is not an HTML file
        Since:
        9

      • getElement

        public abstract Element getElement​(DocTreePath path)
        Returns the language model element referred to by the leaf node of the given DocTreePath, or null if unknown.
        Parameters:
        path - the path for the tree node
        Returns:
        the element

      • getFirstSentence

        public abstract List<DocTree> getFirstSentence​(List<? extends DocTree> list)
        Returns the list of DocTree representing the first sentence of a comment.
        Parameters:
        list - the DocTree list to interrogate
        Returns:
        the first sentence
        Since:
        9

      • getSourcePositions

        public abstract DocSourcePositions getSourcePositions()
        Returns a utility object for accessing the source positions of documentation tree nodes.
        Specified by:
        getSourcePositions in class Trees
        Returns:
        the utility object

      • printMessage

        public abstract void printMessage​(Diagnostic.Kind kind,
                                  CharSequence msg,
                                  DocTree t,
                                  DocCommentTree c,
                                  CompilationUnitTree root)
        Prints a message of the specified kind at the location of the tree within the provided compilation unit
        Parameters:
        kind - the kind of message
        msg - the message, or an empty string if none
        t - the tree to use as a position hint
        c - the doc comment tree to use as a position hint
        root - the compilation unit that contains tree

      • setBreakIterator

        public abstract void setBreakIterator​(BreakIterator breakiterator)
        Sets the break iterator to compute the first sentence of documentation comments.
        Parameters:
        breakiterator - a break iterator or null to specify the default sentence breaker
        Since:
        9

      • getDocTreeFactory

        public abstract DocTreeFactory getDocTreeFactory()
        Returns a utility object for creating DocTree objects.
        Returns:
        a utility object for creating DocTree objects
        Since:
        9