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

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

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