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 TypeMethodDescriptionat
(int pos) Sets the position to be recorded in subsequent tree nodes created by this factory.getFirstSentence
(List<? extends DocTree> list) Gets the first sentence contained in a list of content.newAttributeTree
(Name name, AttributeTree.ValueKind vkind, List<? extends DocTree> value) Creates a newAttributeTree
object, to represent an attribute in an HTML element or tag.newAuthorTree
(List<? extends DocTree> name) Creates a newAuthorTree
object, to represent an@author
tag.newCodeTree
(TextTree text) Creates a newLiteralTree
object, to represent a{@code }
tag.newCommentTree
(String text) Creates a newCommentTree
, to represent an HTML comment.newDeprecatedTree
(List<? extends DocTree> text) Creates a newDeprecatedTree
object, to represent an@deprecated
tag.newDocCommentTree
(List<? extends DocTree> fullBody, List<? extends DocTree> tags) Creates a newDocCommentTree
object, to represent a complete doc comment.newDocCommentTree
(List<? extends DocTree> fullBody, List<? extends DocTree> tags, List<? extends DocTree> preamble, List<? extends DocTree> postamble) Creates a newDocCommentTree
object, to represent the entire doc comment.Creates a newDocRootTree
object, to represent an{@docRoot}
tag.newDocTypeTree
(String text) Creates a newDocTypeTree
, to represent aDOCTYPE
HTML declaration.newEndElementTree
(Name name) Creates a newEndElement
object, to represent the end of an HTML element.newEntityTree
(Name name) Creates a newEntityTree
object, to represent an HTML entity.newErroneousTree
(String text, Diagnostic<JavaFileObject> diag) Creates a newErroneousTree
object, to represent some unparseable input.newEscapeTree
(char ch) Creates a newEscapeTree
object, to represent an escaped character.newExceptionTree
(ReferenceTree name, List<? extends DocTree> description) Creates a newThrowsTree
object, to represent an@exception
tag.newHiddenTree
(List<? extends DocTree> text) Creates a newHiddenTree
object, to represent an@hidden
tag.newIdentifierTree
(Name name) Creates a newIdentifierTree
object, to represent an identifier, such as in a@param
tag.newIndexTree
(DocTree term, List<? extends DocTree> description) Creates a newIndexTree
object, to represent an{@index }
tag.Creates a newInheritDocTree
object, to represent an{@inheritDoc}
tag.newLinkPlainTree
(ReferenceTree ref, List<? extends DocTree> label) Creates a newLinkTree
object, to represent a{@linkplain }
tag.newLinkTree
(ReferenceTree ref, List<? extends DocTree> label) Creates a newLinkTree
object, to represent a{@link }
tag.newLiteralTree
(TextTree text) Creates a newLiteralTree
object, to represent a{@literal }
tag.newParamTree
(boolean isTypeParameter, IdentifierTree name, List<? extends DocTree> description) Creates a newParamTree
object, to represent a@param
tag.newProvidesTree
(ReferenceTree name, List<? extends DocTree> description) Creates a newProvidesTree
object, to represent a@provides
tag.newReferenceTree
(String signature) Creates a newReferenceTree
object, to represent a reference to an API element.default ReturnTree
newReturnTree
(boolean isInline, List<? extends DocTree> description) Creates a newReturnTree
object, to represent a@return
tag or{@return}
tag.newReturnTree
(List<? extends DocTree> description) Creates a newReturnTree
object, to represent a@return
tag.newSeeTree
(List<? extends DocTree> reference) Creates a newSeeTree
object, to represent a@see
tag.newSerialDataTree
(List<? extends DocTree> description) Creates a newSerialDataTree
object, to represent a@serialData
tag.newSerialFieldTree
(IdentifierTree name, ReferenceTree type, List<? extends DocTree> description) Creates a newSerialFieldTree
object, to represent a@serialField
tag.newSerialTree
(List<? extends DocTree> description) Creates a newSerialTree
object, to represent a@serial
tag.newSinceTree
(List<? extends DocTree> text) Creates a newSinceTree
object, to represent a@since
tag.newSnippetTree
(List<? extends DocTree> attributes, TextTree text) Creates a newSnippetTree
object, to represent a{@snippet }
tag.newSpecTree
(TextTree url, List<? extends DocTree> title) Creates a newSpecTree
object, to represent an@spec
tag.newStartElementTree
(Name name, List<? extends DocTree> attrs, boolean selfClosing) Creates a newStartElementTree
object, to represent the start of an HTML element.default SummaryTree
newSummaryTree
(List<? extends DocTree> summary) Creates a newSummaryTree
object, to represent a{@summary }
tag.newSystemPropertyTree
(Name propertyName) Creates a newSystemPropertyTree
object, to represent a{@systemProperty }
tag.newTextTree
(String text) Creates a newTextTree
object, to represent some plain text.newThrowsTree
(ReferenceTree name, List<? extends DocTree> description) Creates a newThrowsTree
object, to represent a@throws
tag.newUnknownBlockTagTree
(Name name, List<? extends DocTree> content) Creates a newUnknownBlockTagTree
object, to represent an unrecognized block tag.newUnknownInlineTagTree
(Name name, List<? extends DocTree> content) Creates a newUnknownInlineTagTree
object, to represent an unrecognized inline tag.newUsesTree
(ReferenceTree name, List<? extends DocTree> description) Creates a newUsesTree
object, to represent a@uses
tag.Creates a newValueTree
object, to represent a{@value }
tag.default ValueTree
newValueTree
(TextTree format, ReferenceTree ref) Creates a newValueTree
object, to represent a{@value }
tag.newVersionTree
(List<? extends DocTree> text) Creates a newVersionTree
object, to represent a{@version }
tag.
-
Method Details
-
newAttributeTree
AttributeTree newAttributeTree(Name name, AttributeTree.ValueKind vkind, List<? extends DocTree> value) Creates a newAttributeTree
object, to represent an attribute in an HTML element or tag.- Parameters:
name
- the name of the attributevkind
- the kind of the attribute valuevalue
- the value, if any, of the attribute- Returns:
- an
AttributeTree
object
-
newAuthorTree
Creates a newAuthorTree
object, to represent an@author
tag.- Parameters:
name
- the name of the author- Returns:
- an
AuthorTree
object
-
newCodeTree
Creates a newLiteralTree
object, to represent a{@code }
tag.- Parameters:
text
- the content of the tag- Returns:
- a
LiteralTree
object
-
newCommentTree
Creates a newCommentTree
, to represent an HTML comment.- Parameters:
text
- the content of the comment- Returns:
- a
CommentTree
object
-
newDeprecatedTree
Creates a newDeprecatedTree
object, to represent an@deprecated
tag.- Parameters:
text
- the content of the tag- Returns:
- a
DeprecatedTree
object
-
newDocCommentTree
Creates a newDocCommentTree
object, to represent a complete doc comment.- Parameters:
fullBody
- the entire body of the doc commenttags
- 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 newDocCommentTree
object, to represent the entire doc comment.- Parameters:
fullBody
- the entire body of the doc commenttags
- the block tags in the doc commentpreamble
- the meta content of an html file including the body tagpostamble
- the meta content of an html including the closing body tag- Returns:
- a
DocCommentTree
object - Since:
- 10
-
newDocRootTree
DocRootTree newDocRootTree()Creates a newDocRootTree
object, to represent an{@docRoot}
tag.- Returns:
- a
DocRootTree
object
-
newDocTypeTree
Creates a newDocTypeTree
, to represent aDOCTYPE
HTML declaration.- Parameters:
text
- the content of the declaration- Returns:
- a
DocTypeTree
object - Since:
- 10
-
newEndElementTree
Creates a newEndElement
object, to represent the end of an HTML element.- Parameters:
name
- the name of the HTML element- Returns:
- an
EndElementTree
object
-
newEntityTree
Creates a newEntityTree
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
Creates a newErroneousTree
object, to represent some unparseable input.- Parameters:
text
- the unparseable textdiag
- a diagnostic associated with the unparseable text, ornull
- Returns:
- an
ErroneousTree
object
-
newEscapeTree
Creates a newEscapeTree
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
Creates a newThrowsTree
object, to represent an@exception
tag.- Parameters:
name
- the name of the exceptiondescription
- a description of why the exception might be thrown- Returns:
- an
ThrowsTree
object
-
newHiddenTree
Creates a newHiddenTree
object, to represent an@hidden
tag.- Parameters:
text
- the content of the tag- Returns:
- a
HiddenTree
object
-
newIdentifierTree
Creates a newIdentifierTree
object, to represent an identifier, such as in a@param
tag.- Parameters:
name
- the name of the identifier- Returns:
- an
IdentifierTree
object
-
newIndexTree
Creates a newIndexTree
object, to represent an{@index }
tag.- Parameters:
term
- the search termdescription
- an optional description of the search term- Returns:
- an
IndexTree
object
-
newInheritDocTree
InheritDocTree newInheritDocTree()Creates a newInheritDocTree
object, to represent an{@inheritDoc}
tag.- Returns:
- an
InheritDocTree
object
-
newLinkTree
Creates a newLinkTree
object, to represent a{@link }
tag.- Parameters:
ref
- the API element being referencedlabel
- an optional label for the link- Returns:
- a
LinkTree
object
-
newLinkPlainTree
Creates a newLinkTree
object, to represent a{@linkplain }
tag.- Parameters:
ref
- the API element being referencedlabel
- an optional label for the link- Returns:
- a
LinkTree
object
-
newLiteralTree
Creates a newLiteralTree
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 newParamTree
object, to represent a@param
tag.- Parameters:
isTypeParameter
-true
if this is a type parameter, andfalse
otherwisename
- the parameter being describeddescription
- the description of the parameter- Returns:
- a
ParamTree
object
-
newProvidesTree
Creates a newProvidesTree
object, to represent a@provides
tag.- Parameters:
name
- the name of the service typedescription
- a description of the service being provided- Returns:
- a
ProvidesTree
object
-
newReferenceTree
Creates a newReferenceTree
object, to represent a reference to an API element.- Parameters:
signature
- the doc comment signature of the reference- Returns:
- a
ReferenceTree
object
-
newReturnTree
Creates a newReturnTree
object, to represent a@return
tag.- Parameters:
description
- the description of the return value of a method- Returns:
- a
ReturnTree
object
-
newReturnTree
Creates a newReturnTree
object, to represent a@return
tag or{@return}
tag.- Implementation Requirements:
- This implementation throws
UnsupportedOperationException
ifisInline
istrue
, and callsnewReturnTree(List)
otherwise. - Parameters:
isInline
-true
if this instance is as an inline tag, andfalse
otherwisedescription
- 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
Creates a newSeeTree
object, to represent a@see
tag.- Parameters:
reference
- the reference- Returns:
- a
SeeTree
object
-
newSerialTree
Creates a newSerialTree
object, to represent a@serial
tag.- Parameters:
description
- the description for the tag- Returns:
- a
SerialTree
object
-
newSerialDataTree
Creates a newSerialDataTree
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 newSerialFieldTree
object, to represent a@serialField
tag.- Parameters:
name
- the name of the fieldtype
- the type of the fielddescription
- the description of the field- Returns:
- a
SerialFieldTree
object
-
newSinceTree
Creates a newSinceTree
object, to represent a@since
tag.- Parameters:
text
- the content of the tag- Returns:
- a
SinceTree
object
-
newSnippetTree
Creates a newSnippetTree
object, to represent a{@snippet }
tag.- Parameters:
attributes
- the attributes of the tagtext
- the body of the tag, ornull
if the tag has no body (not to be confused with an empty body)- Returns:
- a
SnippetTree
object - Since:
- 18
-
newSpecTree
Creates a newSpecTree
object, to represent an@spec
tag.- Parameters:
url
- the urltitle
- the title- Returns:
- a
SpecTree
object - Since:
- 20
-
newStartElementTree
Creates a newStartElementTree
object, to represent the start of an HTML element.- Parameters:
name
- the name of the HTML elementattrs
- the attributesselfClosing
-true
if the start element is marked as self-closing; otherwisefalse
- Returns:
- a
StartElementTree
object
-
newSummaryTree
Creates a newSummaryTree
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
Creates a newSystemPropertyTree
object, to represent a{@systemProperty }
tag.- Parameters:
propertyName
- the system property name- Returns:
- a
SystemPropertyTree
object - Since:
- 12
-
newTextTree
Creates a newTextTree
object, to represent some plain text.- Parameters:
text
- the text- Returns:
- a
TextTree
object
-
newThrowsTree
Creates a newThrowsTree
object, to represent a@throws
tag.- Parameters:
name
- the name of the exceptiondescription
- a description of why the exception might be thrown- Returns:
- a
ThrowsTree
object
-
newUnknownBlockTagTree
Creates a newUnknownBlockTagTree
object, to represent an unrecognized block tag.- Parameters:
name
- the name of the block tagcontent
- the content- Returns:
- an
UnknownBlockTagTree
object
-
newUnknownInlineTagTree
Creates a newUnknownInlineTagTree
object, to represent an unrecognized inline tag.- Parameters:
name
- the name of the inline tagcontent
- the content- Returns:
- an
UnknownInlineTagTree
object
-
newUsesTree
Creates a newUsesTree
object, to represent a@uses
tag.- Parameters:
name
- the name of the service typedescription
- a description of how the service will be used- Returns:
- a
UsesTree
object
-
newValueTree
Creates a newValueTree
object, to represent a{@value }
tag.- Parameters:
ref
- a reference to the value- Returns:
- a
ValueTree
object
-
newValueTree
Creates a newValueTree
object, to represent a{@value }
tag.- Implementation Requirements:
- This implementation calls
newValueTree(ref)
. - Parameters:
format
- a format string for the valueref
- a reference to the value- Returns:
- a
ValueTree
object - Since:
- 20
-
newVersionTree
Creates a newVersionTree
object, to represent a{@version }
tag.- Parameters:
text
- the content of the tag- Returns:
- a
VersionTree
object
-
at
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 orNOPOS
.- Parameters:
pos
- the position- Returns:
- this object, to facilitate method chaining
-
getFirstSentence
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-specificBreakIterator
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
-