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