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

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