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

Methods

Modifier and Type Method Description
DocTreeFactory at​(int pos)

Set the position to be recorded in subsequent tree nodes created by this factory.
List<DocTree> getFirstSentence​(List<? extends DocTree> list)

Get the first sentence contained in a list of content.
AttributeTree newAttributeTree​(Name name, AttributeTree.ValueKind vkind, List<? extends DocTree> value)

Create a new AttributeTree object, to represent an HTML attribute in an HTML tag.
AuthorTree newAuthorTree​(List<? extends DocTree> name)

Create a new AuthorTree object, to represent an {@author } tag.
LiteralTree newCodeTree​(TextTree text)

Create a new CodeTree object, to represent a {@code } tag.
CommentTree newCommentTree​(String text)

Create a new CommentTree, to represent an HTML comment.
DeprecatedTree newDeprecatedTree​(List<? extends DocTree> text)

Create a new DeprecatedTree object, to represent an {@deprecated } tag.
DocCommentTree newDocCommentTree​(List<? extends DocTree> fullBody, List<? extends DocTree> tags)

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

Create a new DocCommentTree object, to represent the enitire doc comment.
DocRootTree newDocRootTree()

Create a new DocRootTree object, to represent an {@docroot} tag.
DocTypeTree newDocTypeTree​(String text)

Create a new DocTypeTree, to represent a DOCTYPE HTML declaration.
EndElementTree newEndElementTree​(Name name)

Create a new EndElement object, to represent the end of an HTML element.
EntityTree newEntityTree​(Name name)

Create a new EntityTree object, to represent an HTML entity.
ErroneousTree newErroneousTree​(String text, Diagnostic<JavaFileObject> diag)

Create a new ErroneousTree object, to represent some unparseable input.
ThrowsTree newExceptionTree​(ReferenceTree name, List<? extends DocTree> description)

Create a new ExceptionTree object, to represent an @exception tag.
HiddenTree newHiddenTree​(List<? extends DocTree> text)

Create a new HiddenTree object, to represent an {@hidden } tag.
IdentifierTree newIdentifierTree​(Name name)

Create a new IdentifierTree object, to represent an identifier, such as in a @param tag.
IndexTree newIndexTree​(DocTree term, List<? extends DocTree> description)

Create a new IndexTree object, to represent an {@index } tag.
InheritDocTree newInheritDocTree()

Create a new InheritDocTree object, to represent an {@inheritDoc} tag.
LinkTree newLinkPlainTree​(ReferenceTree ref, List<? extends DocTree> label)

Create a new LinkPlainTree object, to represent a {@linkplain } tag.
LinkTree newLinkTree​(ReferenceTree ref, List<? extends DocTree> label)

Create a new LinkTree object, to represent a {@link } tag.
LiteralTree newLiteralTree​(TextTree text)

Create a new LiteralTree object, to represent a {@literal } tag.
ParamTree newParamTree​(boolean isTypeParameter, IdentifierTree name, List<? extends DocTree> description)

Create a new ParamTree object, to represent a @param tag.
ProvidesTree newProvidesTree​(ReferenceTree name, List<? extends DocTree> description)

Create a new ProvidesTree object, to represent a @provides tag.
ReferenceTree newReferenceTree​(String signature)

Create a new ReferenceTree object, to represent a reference to an API element.
ReturnTree newReturnTree​(List<? extends DocTree> description)

Create a new ReturnTree object, to represent a @return tag.
SeeTree newSeeTree​(List<? extends DocTree> reference)

Create a new SeeTree object, to represent a @see tag.
SerialDataTree newSerialDataTree​(List<? extends DocTree> description)

Create a new SerialDataTree object, to represent a @serialData tag.
SerialFieldTree newSerialFieldTree​(IdentifierTree name, ReferenceTree type, List<? extends DocTree> description)

Create a new SerialFieldTree object, to represent a @serialField tag.
SerialTree newSerialTree​(List<? extends DocTree> description)

Create a new SerialTree object, to represent a @serial tag.
SinceTree newSinceTree​(List<? extends DocTree> text)

Create a new SinceTree object, to represent a @since tag.
StartElementTree newStartElementTree​(Name name, List<? extends DocTree> attrs, boolean selfClosing)

Create a new StartElementTree object, to represent the start of an HTML element.
default SummaryTree newSummaryTree​(List<? extends DocTree> summary)

Create a new SummaryTree object, to represent a @summary tag.
TextTree newTextTree​(String text)

Create a new TextTree object, to represent some plain text.
ThrowsTree newThrowsTree​(ReferenceTree name, List<? extends DocTree> description)

Create a new ThrowsTree object, to represent a @throws tag.
UnknownBlockTagTree newUnknownBlockTagTree​(Name name, List<? extends DocTree> content)

Create a new UnknownBlockTagTree object, to represent an unrecognized block tag.
UnknownInlineTagTree newUnknownInlineTagTree​(Name name, List<? extends DocTree> content)

Create a new UnknownInlineTagTree object, to represent an unrecognized inline tag.
UsesTree newUsesTree​(ReferenceTree name, List<? extends DocTree> description)

Create a new UsesTree object, to represent a @uses tag.
ValueTree newValueTree​(ReferenceTree ref)

Create a new ValueTree object, to represent a {@value } tag.
VersionTree newVersionTree​(List<? extends DocTree> text)

Create a new VersionTree object, to represent a {@version } tag.

Methods

newAttributeTree

AttributeTree newAttributeTree(Name name,
                               AttributeTree.ValueKind vkind,
                               List<? extends DocTree> value)

Create a new AttributeTree object, to represent an HTML attribute in an HTML tag.

Parameters:
name - the name of the attribute
vkind - the kind of attribute value
value - the value, if any, of the attribute
Returns:
an AttributeTree object

newAuthorTree

AuthorTree newAuthorTree(List<? extends DocTree> name)

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

Create a new CodeTree object, to represent a {@code } tag.

Parameters:
text - the content of the tag
Returns:
a CodeTree object

newCommentTree

CommentTree newCommentTree(String text)

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

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

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

Create a new DocCommentTree object, to represent the enitire 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()

Create a new DocRootTree object, to represent an {@docroot} tag.

Returns:
a DocRootTree object

newDocTypeTree

DocTypeTree newDocTypeTree(String text)

Create a new DocTypeTree, to represent a DOCTYPE HTML declaration.

Parameters:
text - the content of the declaration
Returns:
a CommentTree object
Since:
10

newEndElementTree

EndElementTree newEndElementTree(Name name)

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

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

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

Create a new ExceptionTree 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 ExceptionTree object

newHiddenTree

HiddenTree newHiddenTree(List<? extends DocTree> text)

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

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

Create 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()

Create a new InheritDocTree object, to represent an {@inheritDoc} tag.

Returns:
an InheritDocTree object

newLinkTree

LinkTree newLinkTree(ReferenceTree ref,
                     List<? extends DocTree> label)

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

Create a new LinkPlainTree object, to represent a {@linkplain } tag.

Parameters:
ref - the API element being referenced
label - an optional label for the link
Returns:
a LinkPlainTree object

newLiteralTree

LiteralTree newLiteralTree(TextTree text)

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

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

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

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

Create a new ReturnTree object, to represent a @return tag.

Parameters:
description - the description of the return value of a method
Returns:
a ReturnTree object

newSeeTree

SeeTree newSeeTree(List<? extends DocTree> reference)

Create a new SeeTree object, to represent a @see tag.

Parameters:
reference - the reference
Returns:
a SeeTree object

newSerialTree

SerialTree newSerialTree(List<? extends DocTree> description)

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

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

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

Create a new SinceTree object, to represent a @since tag.

Parameters:
text - the content of the tag
Returns:
a SinceTree object

newStartElementTree

StartElementTree newStartElementTree(Name name,
                                     List<? extends DocTree> attrs,
                                     boolean selfClosing)

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

Create 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

newTextTree

TextTree newTextTree(String text)

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

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

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

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

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

Create a new ValueTree object, to represent a {@value } tag.

Parameters:
ref - a reference to the value
Returns:
a ValueTree object

newVersionTree

VersionTree newVersionTree(List<? extends DocTree> text)

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

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

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