Module jdk.compiler

Package com.sun.source.util

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 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 whose path is specified relative to the given element.
abstract DocCommentTree	getDocCommentTree(FileObject fileObject)	Returns the doc comment tree of the given file.
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.
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 com.sun.source.util.Trees

getDocComment, getElement, getLub, getOriginalType, getPath, getPath, getPath, getPath, getScope, getTree, getTree, getTree, getTree, getTree, getTypeMirror, isAccessible, isAccessible, printMessage

Methods declared in class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

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. 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.

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

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.

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

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

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

External Specifications

• HTML Standard