# 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 attribute in an HTML element or 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.
`EscapeTree`
`newEscapeTree(char ch)`
Creates a new `EscapeTree` object, to represent an escaped character.
`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.
`default InheritDocTree`
`newInheritDocTree(ReferenceTree supertype)`
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.
`RawTextTree`
`newRawTextTree(DocTree.Kind kind, String code)`
Creates a new `RawTextTree` object, to represent a fragment of uninterpreted raw text.
`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.
`SnippetTree`
`newSnippetTree(List<? extends DocTree> attributes, TextTree text)`
Creates a new `SnippetTree` object, to represent a `{@snippet }` tag.
`SpecTree`
`newSpecTree(TextTree url, List<? extends DocTree> title)`
Creates a new `SpecTree` object, to represent an `@spec` 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.
`default ValueTree`
`newValueTree(TextTree format, 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 attribute in an HTML element or 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

### newEscapeTree

EscapeTree newEscapeTree(char ch)
Creates a new `EscapeTree` object, to represent an escaped character.

API Note:
  This method does not itself constrain the set of valid escape sequences, although the set may be effectively constrained to those defined in the Documentation Comment Specification for the Standard Doclet, including the following context-sensitive escape sequences:
  - `@@`, representing `@`, where it would otherwise be treated as introducing a block or inline tag,
  - `@/`, representing `/`, as part of `*@/` to represent `*/`, and
  - `@*`, representing `*`, where it would otherwise be discarded, after whitespace at the beginning of a line.
Parameters:
  `ch` - the character
Returns:
  an `EscapeTree` object
Since:
  21

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

### newInheritDocTree

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

Implementation Requirements:
  This implementation throws `UnsupportedOperationException`.
Parameters:
  `supertype` - a superclass or superinterface reference
Returns:
  an `InheritDocTree` object
Since:
  22

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

### newRawTextTree

RawTextTree newRawTextTree(DocTree.Kind kind, String code)
Creates a new `RawTextTree` object, to represent a fragment of uninterpreted raw text.

Parameters:
  `kind` - the kind of text
  `code` - the code
Returns:
  a `RawTextTree` object
Throws:
  `IllegalArgumentException` - if the kind is not a recognized kind for raw text
Since:
  23

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

### newSnippetTree

SnippetTree newSnippetTree(List<? extends DocTree> attributes, TextTree text)
Creates a new `SnippetTree` object, to represent a `{@snippet }` tag.

Parameters:
  `attributes` - the attributes of the tag
  `text` - the body of the tag, or `null` if the tag has no body (not to be confused with an empty body)
Returns:
  a `SnippetTree` object
Since:
  18

### newSpecTree

SpecTree newSpecTree(TextTree url, List<? extends DocTree> title)
Creates a new `SpecTree` object, to represent an `@spec` tag.

Parameters:
  `url` - the url
  `title` - the title
Returns:
  a `SpecTree` object
Since:
  20

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

### newValueTree

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

Implementation Requirements:
  This implementation calls `newValueTree(ref)`.
Parameters:
  `format` - a format string for the value
  `ref` - a reference to the value
Returns:
  a `ValueTree` object
Since:
  20

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