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

All Methods Instance Methods Abstract Methods
`DocTreeFactory` `at(int pos)` Set the position to be recorded in subsequent tree nodes created by this factory.
`List<DocTree>` `getFirstSentence(List<? extends DocTree> list)` Get the first sentence contained in a list of content.
`AttributeTree` `newAttributeTree(Name name, AttributeTree.ValueKind vkind, List<? extends DocTree> value)` Create a new `AttributeTree` object, to represent an HTML attribute in an HTML tag.
`AuthorTree` `newAuthorTree(List<? extends DocTree> name)` Create a new `AuthorTree` object, to represent an `{@author }` tag.
`LiteralTree` `newCodeTree(TextTree text)` Create a new `CodeTree` object, to represent a `{@code }` tag.
`CommentTree` `newCommentTree(String text)` Create a new `CommentTree`, to represent an HTML comment.
`DeprecatedTree` `newDeprecatedTree(List<? extends DocTree> text)` Create a new `DeprecatedTree` object, to represent an `{@deprecated }` tag.
`DocCommentTree` `newDocCommentTree(List<? extends DocTree> firstSentence, List<? extends DocTree> body, List<? extends DocTree> tags)` Create a new `DocCommentTree` object, to represent a complete doc comment.
`DocRootTree` `newDocRootTree()` Create a new `DocRootTree` object, to represent an `{@docroot}` tag.
`EndElementTree` `newEndElementTree(Name name)` Create a new `EndElement` object, to represent the end of an HTML element.
`EntityTree` `newEntityTree(Name name)` Create a new `EntityTree` object, to represent an HTML entity.
`ErroneousTree` `newErroneousTree(String text, Diagnostic<JavaFileObject> diag)` Create a new `ErroneousTree` object, to represent some unparseable input.
`ThrowsTree` `newExceptionTree(ReferenceTree name, List<? extends DocTree> description)` Create a new `ExceptionTree` object, to represent an `@exception` tag.
`HiddenTree` `newHiddenTree(List<? extends DocTree> text)` Create a new `HiddenTree` object, to represent an `{@hidden }` tag.
`IdentifierTree` `newIdentifierTree(Name name)` Create a new `IdentifierTree` object, to represent an identifier, such as in a `@param` tag.
`IndexTree` `newIndexTree(DocTree term, List<? extends DocTree> description)` Create a new `IndexTree` object, to represent an `{@index }` tag.
`InheritDocTree` `newInheritDocTree()` Create a new `InheritDocTree` object, to represent an `{@inheritDoc}` tag.
`LinkTree` `newLinkPlainTree(ReferenceTree ref, List<? extends DocTree> label)` Create a new `LinkPlainTree` object, to represent a `{@linkplain }` tag.
`LinkTree` `newLinkTree(ReferenceTree ref, List<? extends DocTree> label)` Create a new `LinkTree` object, to represent a `{@link }` tag.
`LiteralTree` `newLiteralTree(TextTree text)` Create a new `LiteralTree` object, to represent a `{@literal }` tag.
`ParamTree` `newParamTree(boolean isTypeParameter, IdentifierTree name, List<? extends DocTree> description)` Create a new `ParamTree` object, to represent a `@param` tag.
`ReferenceTree` `newReferenceTree(String signature)` Create a new `ReferenceTree` object, to represent a reference to an API element.
`ReturnTree` `newReturnTree(List<? extends DocTree> description)` Create a new `ReturnTree` object, to represent a `@return` tag.
`SeeTree` `newSeeTree(List<? extends DocTree> reference)` Create a new `SeeTree` object, to represent a `@see` tag.
`SerialDataTree` `newSerialDataTree(List<? extends DocTree> description)` Create a new `SerialDataTree` object, to represent a `@serialData` tag.
`SerialFieldTree` `newSerialFieldTree(IdentifierTree name, ReferenceTree type, List<? extends DocTree> description)` Create a new `SerialFieldTree` object, to represent a `@serialField` tag.
`SerialTree` `newSerialTree(List<? extends DocTree> description)` Create a new `SerialTree` object, to represent a `@serial` tag.
`SinceTree` `newSinceTree(List<? extends DocTree> text)` Create a new `SinceTree` object, to represent a `@since` tag.
`StartElementTree` `newStartElementTree(Name name, List<? extends DocTree> attrs, boolean selfClosing)` Create a new `StartElementTree` object, to represent the start of an HTML element.
`TextTree` `newTextTree(String text)` Create a new `TextTree` object, to represent some plain text.
`ThrowsTree` `newThrowsTree(ReferenceTree name, List<? extends DocTree> description)` Create a new `ThrowsTree` object, to represent a `@throws` tag.
`UnknownBlockTagTree` `newUnknownBlockTagTree(Name name, List<? extends DocTree> content)` Create a new `UnknownBlockTagTree` object, to represent an unrecognized block tag.
`UnknownInlineTagTree` `newUnknownInlineTagTree(Name name, List<? extends DocTree> content)` Create a new `UnknownInlineTagTree` object, to represent an unrecognized inline tag.
`ValueTree` `newValueTree(ReferenceTree ref)` Create a new `ValueTree` object, to represent a `{@value }` tag.
`VersionTree` `newVersionTree(List<? extends DocTree> text)` Create a new `VersionTree` object, to represent a `{@version }` tag.

### Method Detail

#### newAttributeTree

    AttributeTree newAttributeTree(Name name,
                                   AttributeTree.ValueKind vkind,
                                   List<? extends DocTree> value)

Create a new `AttributeTree` object, to represent an HTML attribute in an HTML tag.

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

#### newAuthorTree

    AuthorTree newAuthorTree(List<? extends DocTree> name)

Create 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)

Create a new `CodeTree` object, to represent a `{@code }` tag.

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

#### newCommentTree

    CommentTree newCommentTree(String text)

Create 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)

Create 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> firstSentence,
                                     List<? extends DocTree> body,
                                     List<? extends DocTree> tags)

Create a new `DocCommentTree` object, to represent a complete doc comment.

Parameters:
  `firstSentence` - the first sentence of the doc comment
  `body` - the body of the doc comment following the first sentence
  `tags` - the block tags in the doc comment
Returns:
  a `DocCommentTree` object

#### newDocRootTree

    DocRootTree newDocRootTree()

Create a new `DocRootTree` object, to represent an `{@docroot}` tag.

Returns:
  a `DocRootTree` object

#### newEndElementTree

    EndElementTree newEndElementTree(Name name)

Create 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)

Create 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)

Create 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)

Create a new `ExceptionTree` 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 `ExceptionTree` object

#### newHiddenTree

    HiddenTree newHiddenTree(List<? extends DocTree> text)

Create 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)

Create 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)

Create 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()

Create a new `InheritDocTree` object, to represent an `{@inheritDoc}` tag.

Returns:
  an `InheritDocTree` object

#### newLinkTree

    LinkTree newLinkTree(ReferenceTree ref,
                         List<? extends DocTree> label)

Create 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)

Create a new `LinkPlainTree` object, to represent a `{@linkplain }` tag.

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

#### newLiteralTree

    LiteralTree newLiteralTree(TextTree text)

Create 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)

Create 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

#### newReferenceTree

    ReferenceTree newReferenceTree(String signature)

Create 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)

Create a new `ReturnTree` object, to represent a `@return` tag.

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

#### newSeeTree

    SeeTree newSeeTree(List<? extends DocTree> reference)

Create a new `SeeTree` object, to represent a `@see` tag.

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

#### newSerialTree

    SerialTree newSerialTree(List<? extends DocTree> description)

Create 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)

Create 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)

Create 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)

Create 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)

Create 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

#### newTextTree

    TextTree newTextTree(String text)

Create 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)

Create 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)

Create 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)

Create 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

#### newValueTree

    ValueTree newValueTree(ReferenceTree ref)

Create 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)

Create 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)

Set 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)

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