OpenJDK 27 · com.sun.source.util.DocTrees · APIdia, the JavaDoc alternative

Access	Constructor and Description
public	DocTrees() Constructor for subclasses to call.

Method Summary

Modifier and Type	Method and Description
public abstract BreakIterator	Returns: the break iterator getBreakIterator() Returns the break iterator used to compute the first sentence of documentation comments.
public abstract String	Returns: a string containing the characters getCharacters(EntityTree the tree containing the entity 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.
public abstract Elements.DocCommentKind	Returns: the style of the documentation comment associated with a tree node getDocCommentKind(TreePath the path for the tree node path) Returns the style of the documentation comment associated with a tree node.
public abstract DocCommentTree	Returns: the doc comment tree getDocCommentTree(TreePath the path for the tree node path) Returns the doc comment tree, if any, for the Tree node identified by a given TreePath.
public abstract DocCommentTree	Returns: the doc comment tree getDocCommentTree(Element an element whose documentation is required e) Returns the doc comment tree of the given element.
public abstract DocCommentTree	Returns: the doc comment tree getDocCommentTree(FileObject the content container fileObject) Returns the doc comment tree of the given file, which must be of one of the supported file types.
public abstract DocCommentTree	Returns: the doc comment tree getDocCommentTree(Element an element whose path is used as a reference e, String the relative path from the Element 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.
public abstract DocTreeFactory	Returns: a utility object for creating `DocTree` objects getDocTreeFactory() Returns a utility object for creating `DocTree` objects.
public abstract DocTreePath	Returns: a doc tree path containing the doc comment parsed from the given file getDocTreePath(FileObject a file object encapsulating the HTML content fileObject, PackageElement a package element to associate with the given file object representing a legacy package.html, null otherwise 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.
public abstract Element	Returns: the referenced element, or null getElement(DocTreePath the path for the tree node path) Returns the language model element referred to by the leaf node of the given `DocTreePath`, or `null` if the leaf node of `path` does not refer to an element.
public abstract List<DocTree>	Returns: the first sentence getFirstSentence(List<? extends DocTree> the DocTree list to interrogate list) Returns the list of `DocTree` representing the first sentence of a comment.
public abstract DocSourcePositions	Returns: the utility object getSourcePositions() Implements abstract com.sun.source.util.Trees.getSourcePositions. Returns a utility object for accessing the source positions of documentation tree nodes.
public abstract TypeMirror	Returns: the referenced type, or null getType(DocTreePath the path for the tree node path) Returns the language model type referred to by the leaf node of the given `DocTreePath`, or `null` if the leaf node of `path` does not refer to a type.
public static DocTrees	Returns: the DocTrees object instance(JavaCompiler.CompilationTask the compilation task for which to get the Trees object task) Hides com.sun.source.util.Trees.instance. Returns a DocTrees object for a given CompilationTask.
public static DocTrees	Returns: the DocTrees object instance(ProcessingEnvironment the processing environment for which to get the Trees object env) Hides com.sun.source.util.Trees.instance. Returns a DocTrees object for a given ProcessingEnvironment.
public abstract void	printMessage(Diagnostic.Kind the kind of message kind, CharSequence the message, or an empty string if none msg, DocTree the tree to use as a position hint t, DocCommentTree the doc comment tree to use as a position hint c, CompilationUnitTree the compilation unit that contains tree root) Prints a message of the specified kind at the location of the tree within the provided compilation unit.
public abstract void	setBreakIterator(BreakIterator a break iterator or `null` to specify the default sentence breaker breakIterator) Sets the break iterator to compute the first sentence of documentation comments.

DocTrees	back to summary
public DocTrees() Constructor for subclasses to call.

Method Detail

getBreakIterator back to summary

getBreakIterator	back to summary
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:BreakIterator the break iterator Since 9

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:BreakIterator: the break iterator
Since: 9

getCharacters back to summary

getCharacters	back to summary
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:EntityTree the tree containing the entity Returns:String a string containing the characters Since 16 External Specification https://www.w3.org/TR/html52

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:EntityTree: the tree containing the entity

Returns:String

a string containing the characters

Since

External Specification

https://www.w3.org/TR/html52

getDocCommentKind back to summary

getDocCommentKind	back to summary
public abstract Elements.DocCommentKind getDocCommentKind(TreePath path) Returns the style of the documentation comment associated with a tree node. Parameters path:TreePath the path for the tree node Returns:Elements.DocCommentKind the style of the documentation comment associated with a tree node Since 23 See Also `Trees#getPath(Element)`

public abstract Elements.DocCommentKind getDocCommentKind(TreePath path)

Returns the style of the documentation comment associated with a tree node.

Parameters

path:TreePath: the path for the tree node

Returns:Elements.DocCommentKind

the style of the documentation comment associated with a tree node

Since

See Also

Trees#getPath(Element)

getDocCommentTree back to summary

getDocCommentTree	back to summary
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:TreePath the path for the tree node Returns:DocCommentTree the doc comment tree

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:TreePath: the path for the tree node

Returns:DocCommentTree

the doc comment tree

getDocCommentTree back to summary

getDocCommentTree	back to summary
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:Element an element whose documentation is required Returns:DocCommentTree the doc comment tree Since 9

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:Element: an element whose documentation is required

Returns:DocCommentTree

the doc comment tree

Since

getDocCommentTree back to summary

getDocCommentTree	back to summary
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:FileObject the content container Returns:DocCommentTree the doc comment tree Exceptions IllegalArgumentException: if the file type is not supported Since 9

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:FileObject: the content container

Returns:DocCommentTree

the doc comment tree

Exceptions

IllegalArgumentException:: if the file type is not supported

Since

getDocCommentTree back to summary

getDocCommentTree	back to summary
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:Element an element whose path is used as a reference relativePath:String the relative path from the Element Returns:DocCommentTree the doc comment tree Exceptions IOException: if an exception occurs IllegalArgumentException: if the file type is not supported Since 9

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:Element: an element whose path is used as a reference
relativePath:String: the relative path from the Element

Returns:DocCommentTree

the doc comment tree

Exceptions

IOException:: if an exception occurs
IllegalArgumentException:: if the file type is not supported

Since

getDocTreeFactory back to summary

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

public abstract DocTreeFactory getDocTreeFactory()

Returns a utility object for creating DocTree objects.

Returns:DocTreeFactory: a utility object for creating DocTree objects
Since: 9

getDocTreePath back to summary

getDocTreePath	back to summary
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:FileObject a file object encapsulating the HTML content packageElement:PackageElement a package element to associate with the given file object representing a legacy package.html, null otherwise Returns:DocTreePath a doc tree path containing the doc comment parsed from the given file Exceptions IllegalArgumentException: if the file type is not supported Since 9

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:FileObject: a file object encapsulating the HTML content
packageElement:PackageElement: a package element to associate with the given file object representing a legacy package.html, null otherwise

Returns:DocTreePath

a doc tree path containing the doc comment parsed from the given file

Exceptions

IllegalArgumentException:: if the file type is not supported

Since

getElement back to summary

getElement	back to summary
public abstract Element getElement(DocTreePath path) Returns the language model element referred to by the leaf node of the given `DocTreePath`, or `null` if the leaf node of `path` does not refer to an element. Parameters path:DocTreePath the path for the tree node Returns:Element the referenced element, or null See Also `getType(DocTreePath)`

public abstract Element getElement(DocTreePath path)

Returns the language model element referred to by the leaf node of the given DocTreePath, or null if the leaf node of path does not refer to an element.

Parameters

path:DocTreePath: the path for the tree node

Returns:Element

the referenced element, or null

See Also

getType(DocTreePath)

getFirstSentence back to summary

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

public abstract List<DocTree> getFirstSentence(List<? extends DocTree> list)

Returns the list of DocTree representing the first sentence of a comment.

Parameters

list:List<? extends DocTree>: the DocTree list to interrogate

Returns:List<DocTree>

the first sentence

Since

getSourcePositions	back to summary
public abstract DocSourcePositions getSourcePositions() Implements abstract com.sun.source.util.Trees.getSourcePositions. Returns a utility object for accessing the source positions of documentation tree nodes. Returns:DocSourcePositions the utility object

getSourcePositions

back to summary

public abstract DocSourcePositions getSourcePositions()

Implements abstract com.sun.source.util.Trees.getSourcePositions.

Returns a utility object for accessing the source positions of documentation tree nodes.

Returns:DocSourcePositions: the utility object

getType back to summary

getType	back to summary
public abstract TypeMirror getType(DocTreePath path) Returns the language model type referred to by the leaf node of the given `DocTreePath`, or `null` if the leaf node of `path` does not refer to a type. If `getElement(DocTreePath)` returns a non-null value for a given `path` argument, this method usally returns the same value as `getElement(path).asType()`. However, there are cases where the returned type includes additional information, such as a parameterized generic type instead of a raw type. In other cases, such as with primitive or array types, the returned type may not have a corresponding element returned by `getElement(DocTreePath)`. Parameters path:DocTreePath the path for the tree node Returns:TypeMirror the referenced type, or null Since 15 See Also `getElement(DocTreePath)`

public abstract TypeMirror getType(DocTreePath path)

Returns the language model type referred to by the leaf node of the given DocTreePath, or null if the leaf node of path does not refer to a type.

If getElement(DocTreePath) returns a non-null value for a given path argument, this method usally returns the same value as getElement(path).asType(). However, there are cases where the returned type includes additional information, such as a parameterized generic type instead of a raw type. In other cases, such as with primitive or array types, the returned type may not have a corresponding element returned by getElement(DocTreePath).

Parameters

path:DocTreePath: the path for the tree node

Returns:TypeMirror

the referenced type, or null

Since

See Also

getElement(DocTreePath)

instance	back to summary
public static DocTrees instance(JavaCompiler.CompilationTask task) Hides com.sun.source.util.Trees.instance. Returns a DocTrees object for a given CompilationTask. Parameters task:JavaCompiler.CompilationTask the compilation task for which to get the Trees object Returns:DocTrees the DocTrees object Exceptions IllegalArgumentException: if the task does not support the Trees API.

instance

back to summary

public static DocTrees instance(JavaCompiler.CompilationTask task)

Hides com.sun.source.util.Trees.instance.

Returns a DocTrees object for a given CompilationTask.

Parameters

task:JavaCompiler.CompilationTask: the compilation task for which to get the Trees object

Returns:DocTrees

the DocTrees object

Exceptions

IllegalArgumentException:: if the task does not support the Trees API.

instance	back to summary
public static DocTrees instance(ProcessingEnvironment env) Hides com.sun.source.util.Trees.instance. Returns a DocTrees object for a given ProcessingEnvironment. Parameters env:ProcessingEnvironment the processing environment for which to get the Trees object Returns:DocTrees the DocTrees object Exceptions IllegalArgumentException: if the env does not support the Trees API.

instance

back to summary

public static DocTrees instance(ProcessingEnvironment env)

Hides com.sun.source.util.Trees.instance.

Returns a DocTrees object for a given ProcessingEnvironment.

Parameters

env:ProcessingEnvironment: the processing environment for which to get the Trees object

Returns:DocTrees

the DocTrees object

Exceptions

IllegalArgumentException:: if the env does not support the Trees API.

printMessage	back to summary
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:Diagnostic.Kind the kind of message msg:CharSequence the message, or an empty string if none t:DocTree the tree to use as a position hint c:DocCommentTree the doc comment tree to use as a position hint root:CompilationUnitTree the compilation unit that contains tree

printMessage

back to summary

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:Diagnostic.Kind: the kind of message
msg:CharSequence: the message, or an empty string if none
t:DocTree: the tree to use as a position hint
c:DocCommentTree: the doc comment tree to use as a position hint
root:CompilationUnitTree: the compilation unit that contains tree

setBreakIterator back to summary

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

public abstract void setBreakIterator(BreakIterator breakIterator)

Sets the break iterator to compute the first sentence of documentation comments.

Parameters

breakIterator:BreakIterator: a break iterator or null to specify the default sentence breaker

Since

public abstract Class DocTrees

Constructor Summary

Method Summary

Constructor Detail

Method Detail