Class DocTrees

java.lang.Object
com.sun.source.util.Trees
com.sun.source.util.DocTrees
public abstract class DocTrees extends Trees
Provides access to syntax trees for doc comments.
Since:
1.8

  • Constructor Details

    • DocTrees

      public DocTrees()
      Constructor for subclasses to call.

  • Method Details

    • 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

    • getDocCommentKind

      public abstract Elements.DocCommentKind getDocCommentKind(TreePath path)
      Returns the style of the documentation comment associated with a tree node.
      Parameters:
      path - the path for the tree node
      Returns:
      the style of the documentation comment associated with a tree node
      Since:
      23
      See Also:

    • 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.
      Implementation Note:
      The default implementation of this method returns the same DocCommentTree instance for repeated invocations with the same argument.
      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.
      Implementation Note:
      The default implementation of this method returns the same DocCommentTree instance for repeated invocations with the same argument.
      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, which must be of one of the supported file types.

      The supported file types are:

      • HTML files, identified by a file name ending in .html,
      • Markdown files, identified by a file name ending in .md.
      Future releases may support additional file types.
      Implementation Note:
      The default implementation of this method returns a new DocCommentTree instance for each invocation.
      Parameters:
      fileObject - the content container
      Returns:
      the doc comment tree
      Throws:
      IllegalArgumentException - if the file type is not supported
      Since:
      9

    • getDocCommentTree

      public abstract DocCommentTree getDocCommentTree(Element e, String relativePath) throws IOException
      Returns the doc comment tree of the given file, which must be of one of the supported file types, and whose path is specified relative to the given element.

      The supported file types are:

      • HTML files, identified by a file name ending in .html,
      • Markdown files, identified by a file name ending in .md.
      Future releases may support additional file types.
      Implementation Note:
      The default implementation of this method returns a new DocCommentTree instance for each invocation.
      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
      IllegalArgumentException - if the file type is not supported
      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, which must be of one of the supported file types. Supported file types are HTML files and Markdown files. Future releases may support additional file types. 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 file type is not supported
      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

    • getType

      public abstract TypeMirror getType(DocTreePath path)
      Returns the language model type referred to by the leaf node of the given DocTreePath, or null if unknown. This method usually returns the same value as getElement(path).asType() for a path argument for which getElement(DocTreePath) returns a non-null value, but may return a type that includes additional information, such as a parameterized generic type instead of a raw type.
      Parameters:
      path - the path for the tree node
      Returns:
      the referenced type, or null
      Since:
      15

    • 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

    • getCharacters

      public abstract String getCharacters(EntityTree tree)
      Returns a string containing the characters for the entity in a given entity tree, or null if the tree does not represent a valid series of characters.

      The interpretation of entities is based on section 8.1.4. Character references in the HTML 5.2 specification.

      Parameters:
      tree - the tree containing the entity
      Returns:
      a string containing the characters
      Since:
      16
      External Specifications