# 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 Summary

  Constructors
  Constructor
  Description
  `DocTrees()`
  Constructor for subclasses to call.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract BreakIterator`
  `getBreakIterator()`
  Returns the break iterator used to compute the first sentence of documentation comments.
  `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.
  `abstract Elements.DocCommentKind`
  `getDocCommentKind(TreePath path)`
  Returns the style of the documentation comment associated with a tree node.
  `abstract DocCommentTree`
  `getDocCommentTree(TreePath path)`
  Returns the doc comment tree, if any, for the Tree node identified by a given TreePath.
  `abstract DocCommentTree`
  `getDocCommentTree(Element e)`
  Returns the doc comment tree of the given element.
  `abstract DocCommentTree`
  `getDocCommentTree(Element e, String relativePath)`
  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.
  `abstract DocCommentTree`
  `getDocCommentTree(FileObject fileObject)`
  Returns the doc comment tree of the given file, which must be of one of the supported file types.
  `abstract DocTreeFactory`
  `getDocTreeFactory()`
  Returns a utility object for creating `DocTree` objects.
  `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.
  `abstract Element`
  `getElement(DocTreePath path)`
  Returns the language model element referred to by the leaf node of the given `DocTreePath`, or `null` if unknown.
  `abstract List<DocTree>`
  `getFirstSentence(List<? extends DocTree> list)`
  Returns the list of `DocTree` representing the first sentence of a comment.
  `abstract DocSourcePositions`
  `getSourcePositions()`
  Returns a utility object for accessing the source positions of documentation tree nodes.
  `abstract TypeMirror`
  `getType(DocTreePath path)`
  Returns the language model type referred to by the leaf node of the given `DocTreePath`, or `null` if unknown.
  `static DocTrees`
  `instance(ProcessingEnvironment env)`
  Returns a DocTrees object for a given ProcessingEnvironment.
  `static DocTrees`
  `instance(JavaCompiler.CompilationTask task)`
  Returns a DocTrees object for a given CompilationTask.
  `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.
  `abstract void`
  `setBreakIterator(BreakIterator breakIterator)`
  Sets the break iterator to compute the first sentence of documentation comments.

  ### Methods declared in class Trees

  `getDocComment, getElement, getLub, getOriginalType, getPath, getPath, getPath, getPath, getScope, getTree, getTree, getTree, getTree, getTree, getTypeMirror, isAccessible, isAccessible, printMessage`
  Modifier and Type
  Method
  Description
  `abstract String`
  `getDocComment(TreePath path)`
  Returns the doc comment, if any, for the `Tree` node identified by a given `TreePath`.
  `abstract Element`
  `getElement(TreePath path)`
  Returns the `Element` for the `Tree` node identified by a given `TreePath`.
  `abstract TypeMirror`
  `getLub(CatchTree tree)`
  Returns the lub of an exception parameter declared in a catch clause.
  `abstract TypeMirror`
  `getOriginalType(ErrorType errorType)`
  Returns the original type from the `ErrorType` object.
  `abstract TreePath`
  `getPath(CompilationUnitTree unit, Tree node)`
  Returns the path to tree node within the specified compilation unit.
  `abstract TreePath`
  `getPath(Element e)`
  Returns the `TreePath` node for a given `Element`.
  `abstract TreePath`
  `getPath(Element e, AnnotationMirror a)`
  Returns the `TreePath` node for an `AnnotationMirror` on a given `Element`.
  `abstract TreePath`
  `getPath(Element e, AnnotationMirror a, AnnotationValue v)`
  Returns the `TreePath` node for an `AnnotationValue` for an `AnnotationMirror` on a given `Element`.
  `abstract Scope`
  `getScope(TreePath path)`
  Returns the `Scope` for the `Tree` node identified by a given `TreePath`.
  `abstract Tree`
  `getTree(Element element)`
  Returns the `Tree` node for a given `Element`.
  `abstract Tree`
  `getTree(Element e, AnnotationMirror a)`
  Returns the `Tree` node for an `AnnotationMirror` on a given `Element`.
  `abstract Tree`
  `getTree(Element e, AnnotationMirror a, AnnotationValue v)`
  Returns the `Tree` node for an `AnnotationValue` for an `AnnotationMirror` on a given `Element`.
  `abstract MethodTree`
  `getTree(ExecutableElement method)`
  Returns the `MethodTree` node for a given `ExecutableElement`.
  `abstract ClassTree`
  `getTree(TypeElement element)`
  Returns the `ClassTree` node for a given `TypeElement`.
  `abstract TypeMirror`
  `getTypeMirror(TreePath path)`
  Returns the `TypeMirror` for the `Tree` node identified by a given `TreePath`.
  `abstract boolean`
  `isAccessible(Scope scope, Element member, DeclaredType type)`
  Checks whether the given element is accessible as a member of the given type in a given scope.
  `abstract boolean`
  `isAccessible(Scope scope, TypeElement type)`
  Checks whether a given type is accessible in a given scope.
  `abstract void`
  `printMessage(Diagnostic.Kind kind, CharSequence msg, Tree t, CompilationUnitTree root)`
  Prints a message of the specified kind at the location of the tree within the provided compilation unit

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## 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:
      - `Trees.getPath(Element)`

  - ### 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
      - HTML Standard