W3cubDocs

/OpenJDK 21

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 &ast;&sol;, 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

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.compiler/com/sun/source/util/DocTreeFactory.html