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.
default InheritDocTree	newInheritDocTree(ReferenceTree supertype)	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

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

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