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

# Interface DocTreeFactory

public interface DocTreeFactory
Factory for creating `DocTree` nodes.

Implementation Note:
  The methods in an implementation of this interface may only accept `DocTree` nodes that have been created by the same implementation.
Since:
  9

## Method Summary

Modifier and Type
Method
Description
`DocTreeFactory`
`at(int pos)`
Sets the position to be recorded in subsequent tree nodes created by this factory.
`List<DocTree>`
`getFirstSentence(List<? extends DocTree> list)`
Gets the first sentence contained in a list of content.
`AttributeTree`
`newAttributeTree(Name name, AttributeTree.ValueKind vkind, List<? extends DocTree> value)`
Creates a new `AttributeTree` object, to represent an HTML attribute in an HTML tag.
`AuthorTree`
`newAuthorTree(List<? extends DocTree> name)`
Creates a new `AuthorTree` object, to represent an `@author` tag.
`LiteralTree`
`newCodeTree(TextTree text)`
Creates a new `LiteralTree` object, to represent a `{@code }` tag.
`CommentTree`
`newCommentTree(String text)`
Creates a new `CommentTree`, to represent an HTML comment.
`DeprecatedTree`
`newDeprecatedTree(List<? extends DocTree> text)`
Creates a new `DeprecatedTree` object, to represent an `@deprecated` tag.
`DocCommentTree`
`newDocCommentTree(List<? extends DocTree> fullBody, List<? extends DocTree> tags)`
Creates a new `DocCommentTree` object, to represent a complete doc comment.
`DocCommentTree`
`newDocCommentTree(List<? extends DocTree> fullBody, List<? extends DocTree> tags, List<? extends DocTree> preamble, List<? extends DocTree> postamble)`
Creates a new `DocCommentTree` object, to represent the entire doc comment.
`DocRootTree`
`newDocRootTree()`
Creates a new `DocRootTree` object, to represent an `{@docRoot}` tag.
`DocTypeTree`
`newDocTypeTree(String text)`
Creates a new `DocTypeTree`, to represent a `DOCTYPE` HTML declaration.
`EndElementTree`
`newEndElementTree(Name name)`
Creates a new `EndElement` object, to represent the end of an HTML element.
`EntityTree`
`newEntityTree(Name name)`
Creates a new `EntityTree` object, to represent an HTML entity.
`ErroneousTree`
`newErroneousTree(String text, Diagnostic<JavaFileObject> diag)`
Creates a new `ErroneousTree` object, to represent some unparseable input.
`ThrowsTree`
`newExceptionTree(ReferenceTree name, List<? extends DocTree> description)`
Creates a new `ThrowsTree` object, to represent an `@exception` tag.
`HiddenTree`
`newHiddenTree(List<? extends DocTree> text)`
Creates a new `HiddenTree` object, to represent an `@hidden` tag.
`IdentifierTree`
`newIdentifierTree(Name name)`
Creates a new `IdentifierTree` object, to represent an identifier, such as in a `@param` tag.
`IndexTree`
`newIndexTree(DocTree term, List<? extends DocTree> description)`
Creates a new `IndexTree` object, to represent an `{@index }` tag.
`InheritDocTree`
`newInheritDocTree()`
Creates a new `InheritDocTree` object, to represent an `{@inheritDoc}` tag.
`LinkTree`
`newLinkPlainTree(ReferenceTree ref, List<? extends DocTree> label)`
Creates a new `LinkTree` object, to represent a `{@linkplain }` tag.
`LinkTree`
`newLinkTree(ReferenceTree ref, List<? extends DocTree> label)`
Creates a new `LinkTree` object, to represent a `{@link }` tag.
`LiteralTree`
`newLiteralTree(TextTree text)`
Creates a new `LiteralTree` object, to represent a `{@literal }` tag.
`ParamTree`
`newParamTree(boolean isTypeParameter, IdentifierTree name, List<? extends DocTree> description)`
Creates a new `ParamTree` object, to represent a `@param` tag.
`ProvidesTree`
`newProvidesTree(ReferenceTree name, List<? extends DocTree> description)`
Creates a new `ProvidesTree` object, to represent a `@provides` tag.
`ReferenceTree`
`newReferenceTree(String signature)`
Creates a new `ReferenceTree` object, to represent a reference to an API element.
`default ReturnTree`
`newReturnTree(boolean isInline, List<? extends DocTree> description)`
Creates a new `ReturnTree` object, to represent a `@return` tag or `{@return}` tag.
`ReturnTree`
`newReturnTree(List<? extends DocTree> description)`
Creates a new `ReturnTree` object, to represent a `@return` tag.
`SeeTree`
`newSeeTree(List<? extends DocTree> reference)`
Creates a new `SeeTree` object, to represent a `@see` tag.
`SerialDataTree`
`newSerialDataTree(List<? extends DocTree> description)`
Creates a new `SerialDataTree` object, to represent a `@serialData` tag.
`SerialFieldTree`
`newSerialFieldTree(IdentifierTree name, ReferenceTree type, List<? extends DocTree> description)`
Creates a new `SerialFieldTree` object, to represent a `@serialField` tag.
`SerialTree`
`newSerialTree(List<? extends DocTree> description)`
Creates a new `SerialTree` object, to represent a `@serial` tag.
`SinceTree`
`newSinceTree(List<? extends DocTree> text)`
Creates a new `SinceTree` object, to represent a `@since` tag.
`StartElementTree`
`newStartElementTree(Name name, List<? extends DocTree> attrs, boolean selfClosing)`
Creates a new `StartElementTree` object, to represent the start of an HTML element.
`default SummaryTree`
`newSummaryTree(List<? extends DocTree> summary)`
Creates a new `SummaryTree` object, to represent a `{@summary }` tag.
`SystemPropertyTree`
`newSystemPropertyTree(Name propertyName)`
Creates a new `SystemPropertyTree` object, to represent a `{@systemProperty }` tag.
`TextTree`
`newTextTree(String text)`
Creates a new `TextTree` object, to represent some plain text.
`ThrowsTree`
`newThrowsTree(ReferenceTree name, List<? extends DocTree> description)`
Creates a new `ThrowsTree` object, to represent a `@throws` tag.
`UnknownBlockTagTree`
`newUnknownBlockTagTree(Name name, List<? extends DocTree> content)`
Creates a new `UnknownBlockTagTree` object, to represent an unrecognized block tag.
`UnknownInlineTagTree`
`newUnknownInlineTagTree(Name name, List<? extends DocTree> content)`
Creates a new `UnknownInlineTagTree` object, to represent an unrecognized inline tag.
`UsesTree`
`newUsesTree(ReferenceTree name, List<? extends DocTree> description)`
Creates a new `UsesTree` object, to represent a `@uses` tag.
`ValueTree`
`newValueTree(ReferenceTree ref)`
Creates a new `ValueTree` object, to represent a `{@value }` tag.
`VersionTree`
`newVersionTree(List<? extends DocTree> text)`
Creates a new `VersionTree` object, to represent a `{@version }` tag.

## Method Details

### newAttributeTree

AttributeTree newAttributeTree(Name name, AttributeTree.ValueKind vkind, List<? extends DocTree> value)
Creates a new `AttributeTree` object, to represent an HTML attribute in an HTML tag.

Parameters:
  `name` - the name of the attribute
  `vkind` - the kind of the attribute value
  `value` - the value, if any, of the attribute
Returns:
  an `AttributeTree` object

### newAuthorTree

AuthorTree newAuthorTree(List<? extends DocTree> name)
Creates a new `AuthorTree` object, to represent an `@author` tag.

Parameters:
  `name` - the name of the author
Returns:
  an `AuthorTree` object

### newCodeTree

LiteralTree newCodeTree(TextTree text)
Creates a new `LiteralTree` object, to represent a `{@code }` tag.

Parameters:
  `text` - the content of the tag
Returns:
  a `LiteralTree` object

### newCommentTree

CommentTree newCommentTree(String text)
Creates a new `CommentTree`, to represent an HTML comment.

Parameters:
  `text` - the content of the comment
Returns:
  a `CommentTree` object

### newDeprecatedTree

DeprecatedTree newDeprecatedTree(List<? extends DocTree> text)
Creates a new `DeprecatedTree` object, to represent an `@deprecated` tag.

Parameters:
  `text` - the content of the tag
Returns:
  a `DeprecatedTree` object

### newDocCommentTree

DocCommentTree newDocCommentTree(List<? extends DocTree> fullBody, List<? extends DocTree> tags)
Creates a new `DocCommentTree` object, to represent a complete doc comment.

Parameters:
  `fullBody` - the entire body of the doc comment
  `tags` - the block tags in the doc comment
Returns:
  a `DocCommentTree` object

### newDocCommentTree

DocCommentTree newDocCommentTree(List<? extends DocTree> fullBody, List<? extends DocTree> tags, List<? extends DocTree> preamble, List<? extends DocTree> postamble)
Creates a new `DocCommentTree` object, to represent the entire doc comment.

Parameters:
  `fullBody` - the entire body of the doc comment
  `tags` - the block tags in the doc comment
  `preamble` - the meta content of an html file including the body tag
  `postamble` - the meta content of an html including the closing body tag
Returns:
  a `DocCommentTree` object
Since:
  10

### newDocRootTree

DocRootTree newDocRootTree()
Creates a new `DocRootTree` object, to represent an `{@docRoot}` tag.

Returns:
  a `DocRootTree` object

### newDocTypeTree

DocTypeTree newDocTypeTree(String text)
Creates a new `DocTypeTree`, to represent a `DOCTYPE` HTML declaration.

Parameters:
  `text` - the content of the declaration
Returns:
  a `DocTypeTree` object
Since:
  10

### newEndElementTree

EndElementTree newEndElementTree(Name name)
Creates a new `EndElement` object, to represent the end of an HTML element.

Parameters:
  `name` - the name of the HTML element
Returns:
  an `EndElementTree` object

### newEntityTree

EntityTree newEntityTree(Name name)
Creates a new `EntityTree` object, to represent an HTML entity.

Parameters:
  `name` - the name of the entity, representing the characters between '&' and ';' in the representation of the entity in an HTML document
Returns:
  an `EntityTree` object

### newErroneousTree

ErroneousTree newErroneousTree(String text, Diagnostic<JavaFileObject> diag)
Creates a new `ErroneousTree` object, to represent some unparseable input.

Parameters:
  `text` - the unparseable text
  `diag` - a diagnostic associated with the unparseable text, or `null`
Returns:
  an `ErroneousTree` object

### newExceptionTree

ThrowsTree newExceptionTree(ReferenceTree name, List<? extends DocTree> description)
Creates a new `ThrowsTree` object, to represent an `@exception` tag.

Parameters:
  `name` - the name of the exception
  `description` - a description of why the exception might be thrown
Returns:
  an `ThrowsTree` object

### newHiddenTree

HiddenTree newHiddenTree(List<? extends DocTree> text)
Creates a new `HiddenTree` object, to represent an `@hidden` tag.

Parameters:
  `text` - the content of the tag
Returns:
  a `HiddenTree` object

### newIdentifierTree

IdentifierTree newIdentifierTree(Name name)
Creates a new `IdentifierTree` object, to represent an identifier, such as in a `@param` tag.

Parameters:
  `name` - the name of the identifier
Returns:
  an `IdentifierTree` object

### newIndexTree

IndexTree newIndexTree(DocTree term, List<? extends DocTree> description)
Creates a new `IndexTree` object, to represent an `{@index }` tag.

Parameters:
  `term` - the search term
  `description` - an optional description of the search term
Returns:
  an `IndexTree` object

### newInheritDocTree

InheritDocTree newInheritDocTree()
Creates a new `InheritDocTree` object, to represent an `{@inheritDoc}` tag.

Returns:
  an `InheritDocTree` object

### newLinkTree

LinkTree newLinkTree(ReferenceTree ref, List<? extends DocTree> label)
Creates a new `LinkTree` object, to represent a `{@link }` tag.

Parameters:
  `ref` - the API element being referenced
  `label` - an optional label for the link
Returns:
  a `LinkTree` object

### newLinkPlainTree

LinkTree newLinkPlainTree(ReferenceTree ref, List<? extends DocTree> label)
Creates a new `LinkTree` object, to represent a `{@linkplain }` tag.

Parameters:
  `ref` - the API element being referenced
  `label` - an optional label for the link
Returns:
  a `LinkTree` object

### newLiteralTree

LiteralTree newLiteralTree(TextTree text)
Creates a new `LiteralTree` object, to represent a `{@literal }` tag.

Parameters:
  `text` - the content of the tag
Returns:
  a `LiteralTree` object

### newParamTree

ParamTree newParamTree(boolean isTypeParameter, IdentifierTree name, List<? extends DocTree> description)
Creates a new `ParamTree` object, to represent a `@param` tag.

Parameters:
  `isTypeParameter` - `true` if this is a type parameter, and `false` otherwise
  `name` - the parameter being described
  `description` - the description of the parameter
Returns:
  a `ParamTree` object

### newProvidesTree

ProvidesTree newProvidesTree(ReferenceTree name, List<? extends DocTree> description)
Creates a new `ProvidesTree` object, to represent a `@provides` tag.

Parameters:
  `name` - the name of the service type
  `description` - a description of the service being provided
Returns:
  a `ProvidesTree` object

### newReferenceTree

ReferenceTree newReferenceTree(String signature)
Creates a new `ReferenceTree` object, to represent a reference to an API element.

Parameters:
  `signature` - the doc comment signature of the reference
Returns:
  a `ReferenceTree` object

### newReturnTree

ReturnTree newReturnTree(List<? extends DocTree> description)
Creates a new `ReturnTree` object, to represent a `@return` tag.

Parameters:
  `description` - the description of the return value of a method
Returns:
  a `ReturnTree` object

### newReturnTree

default ReturnTree newReturnTree(boolean isInline, List<? extends DocTree> description)
Creates a new `ReturnTree` object, to represent a `@return` tag or `{@return}` tag.

Implementation Requirements:
  This implementation throws `UnsupportedOperationException` if `isInline` is `true`, and calls `newReturnTree(List)` otherwise.
Parameters:
  `isInline` - `true` if this instance is as an inline tag, and `false` otherwise
  `description` - the description of the return value of a method
Returns:
  a `ReturnTree` object
Throws:
  `UnsupportedOperationException` - if inline `{@return}` tags are not supported
Since:
  16

### newSeeTree

SeeTree newSeeTree(List<? extends DocTree> reference)
Creates a new `SeeTree` object, to represent a `@see` tag.

Parameters:
  `reference` - the reference
Returns:
  a `SeeTree` object

### newSerialTree

SerialTree newSerialTree(List<? extends DocTree> description)
Creates a new `SerialTree` object, to represent a `@serial` tag.

Parameters:
  `description` - the description for the tag
Returns:
  a `SerialTree` object

### newSerialDataTree

SerialDataTree newSerialDataTree(List<? extends DocTree> description)
Creates a new `SerialDataTree` object, to represent a `@serialData` tag.

Parameters:
  `description` - the description for the tag
Returns:
  a `SerialDataTree` object

### newSerialFieldTree

SerialFieldTree newSerialFieldTree(IdentifierTree name, ReferenceTree type, List<? extends DocTree> description)
Creates a new `SerialFieldTree` object, to represent a `@serialField` tag.

Parameters:
  `name` - the name of the field
  `type` - the type of the field
  `description` - the description of the field
Returns:
  a `SerialFieldTree` object

### newSinceTree

SinceTree newSinceTree(List<? extends DocTree> text)
Creates a new `SinceTree` object, to represent a `@since` tag.

Parameters:
  `text` - the content of the tag
Returns:
  a `SinceTree` object

### newStartElementTree

StartElementTree newStartElementTree(Name name, List<? extends DocTree> attrs, boolean selfClosing)
Creates a new `StartElementTree` object, to represent the start of an HTML element.

Parameters:
  `name` - the name of the HTML element
  `attrs` - the attributes
  `selfClosing` - `true` if the start element is marked as self-closing; otherwise `false`
Returns:
  a `StartElementTree` object

### newSummaryTree

default SummaryTree newSummaryTree(List<? extends DocTree> summary)
Creates a new `SummaryTree` object, to represent a `{@summary }` tag.

Implementation Requirements:
  This implementation throws `UnsupportedOperationException`.
Parameters:
  `summary` - the content of the tag
Returns:
  a `SummaryTree` object
Since:
  10

### newSystemPropertyTree

SystemPropertyTree newSystemPropertyTree(Name propertyName)
Creates a new `SystemPropertyTree` object, to represent a `{@systemProperty }` tag.

Parameters:
  `propertyName` - the system property name
Returns:
  a `SystemPropertyTree` object
Since:
  12

### newTextTree

TextTree newTextTree(String text)
Creates a new `TextTree` object, to represent some plain text.

Parameters:
  `text` - the text
Returns:
  a `TextTree` object

### newThrowsTree

ThrowsTree newThrowsTree(ReferenceTree name, List<? extends DocTree> description)
Creates a new `ThrowsTree` object, to represent a `@throws` tag.

Parameters:
  `name` - the name of the exception
  `description` - a description of why the exception might be thrown
Returns:
  a `ThrowsTree` object

### newUnknownBlockTagTree

UnknownBlockTagTree newUnknownBlockTagTree(Name name, List<? extends DocTree> content)
Creates a new `UnknownBlockTagTree` object, to represent an unrecognized block tag.

Parameters:
  `name` - the name of the block tag
  `content` - the content
Returns:
  an `UnknownBlockTagTree` object

### newUnknownInlineTagTree

UnknownInlineTagTree newUnknownInlineTagTree(Name name, List<? extends DocTree> content)
Creates a new `UnknownInlineTagTree` object, to represent an unrecognized inline tag.

Parameters:
  `name` - the name of the inline tag
  `content` - the content
Returns:
  an `UnknownInlineTagTree` object

### newUsesTree

UsesTree newUsesTree(ReferenceTree name, List<? extends DocTree> description)
Creates a new `UsesTree` object, to represent a `@uses` tag.

Parameters:
  `name` - the name of the service type
  `description` - a description of how the service will be used
Returns:
  a `UsesTree` object

### newValueTree

ValueTree newValueTree(ReferenceTree ref)
Creates a new `ValueTree` object, to represent a `{@value }` tag.

Parameters:
  `ref` - a reference to the value
Returns:
  a `ValueTree` object

### newVersionTree

VersionTree newVersionTree(List<? extends DocTree> text)
Creates a new `VersionTree` object, to represent a `{@version }` tag.

Parameters:
  `text` - the content of the tag
Returns:
  a `VersionTree` object

### at

DocTreeFactory at(int pos)
Sets the position to be recorded in subsequent tree nodes created by this factory. The position should be a character offset relative to the beginning of the source file or `NOPOS`.

Parameters:
  `pos` - the position
Returns:
  this object, to facilitate method chaining

### getFirstSentence

List<DocTree> getFirstSentence(List<? extends DocTree> list)
Gets the first sentence contained in a list of content. The determination of the first sentence is implementation specific, and may involve the use of a locale-specific `BreakIterator` and other heuristics. The resulting list may share a common set of initial items with the input list.

Parameters:
  `list` - the list
Returns:
  a list containing the first sentence of the list