oracle.javatools.parser.java.v2.model.doc

Interface SourceDocComment

All Superinterfaces:

Element, SourceDocElement, SourceDocHasDescription, SourceElement

public interface SourceDocComment
extends SourceDocHasDescription

A SourceDocComment represents a documentation comment ("doc comment") associated with a class, interface, constructor, method, or field. Doc comments are also known informally as "Javadoc comments" (but this term violates its trademark usage). A doc comment has a main description, which is the text preceding the first block tag, and zero or more block tags. Both the main description and the descriptions contained by most block tags may contain inline tags.

The children of a doc comment are the following:

• a SourceDocDescription for the main description, if any;
• for each block tag, a SourceDocBlockTag.

TODO Packages also have documentation comments (package.html) and they are represented in the Doclet API: I'm ignoring them for now.

See Also:

SourceDocDescription, SourceDocTag, SourceDocBlockTag, SourceDocInlineTag

Field Summary

Fields inherited from interface oracle.javatools.parser.java.v2.model.SourceElement

CHILDREN_ALL, CHILDREN_BLANKLINES, CHILDREN_COMMENTS, CHILDREN_default, CHILDREN_none, CHILDREN_REGULAR, EMPTY_ARRAY, PRINT_ALL, REFORMAT_ALL, REFORMAT_INDENT

Method Summary

Methods

Modifier and Type	Method and Description
SourceDocBlockTag	findExceptionTag(java.lang.String exceptionName) Finds the first @exception or @throws tag in this doc comment with a specified fully-qualified name.
java.util.Collection<SourceDocBlockTag>	findExceptionTags() Finds the @exception or @throws tags in this doc comment.
SourceDocBlockTag	findParameterTag(java.lang.String parameterName) Finds the first @param tag in this doc comment with a specified name.
java.util.Collection<SourceDocTag>	findReferenceTags() Finds the @link, @linkplain, @see, and three-element @value tags in this doc comment.
java.util.Collection<SourceDocTag>	findReferenceTags(java.lang.String referenceText) Finds the @link, @linkplain, @see, and three-element @value tags in this doc comment with a specified normalized reference text.
java.util.Collection<SourceDocTag>	findTags(java.lang.String name) Finds the tags in this doc comment with a specified name, or an empty list if none.
java.util.List<SourceDocBlockTag>	getBlockTags() Gets the block tags from this doc comment.
SourceDocDescription	getDescription() Gets the main description, the text before the first block tag, from this doc comment.

Methods inherited from interface oracle.javatools.parser.java.v2.model.doc.SourceDocHasDescription

setDescription

Methods inherited from interface oracle.javatools.parser.java.v2.model.doc.SourceDocElement

getDocText, getInlineTags, getOwningDocComment, getOwningMember, getReferences, isBlank

Methods inherited from interface oracle.javatools.parser.java.v2.model.SourceElement

addSelf, addSelf, addSelfAfter, addSelfBefore, adjustTextIndentation, clearBinding, cloneSelf, compile, getBinding, getChildren, getChildren, getCompiledObject, getContainedElements, getEndOffset, getJdkVersion, getOwningFile, getOwningSourceFile, getParent, getSiblingAfter, getSiblingBefore, getSiblings, getSiblings, getStartOffset, getSymbolKind, getText, getTokens, hasErrors, print, print, reformatSelf, removeSelf, replaceSelf, resolve, setBinding, setContext, visitSelf

Method Detail

getDescription

SourceDocDescription getDescription()

Gets the main description, the text before the first block tag, from this doc comment.

Specified by:

getDescription in interface SourceDocHasDescription

Returns:

the description of this doc comment, or null if none.

getBlockTags

java.util.List<SourceDocBlockTag> getBlockTags()

Gets the block tags from this doc comment.

Returns:

A possibly empty list of SourceDocBlockTags, one for each block tag in this doc comment, in document order.

findTags

java.util.Collection<SourceDocTag> findTags(java.lang.String name)

Finds the tags in this doc comment with a specified name, or an empty list if none. In-line tags are searched for within both the main description and block tag descriptions.

Parameters:

name - the name of a tag to find. The tag name must include the leading "@" character.

Returns:

a possibly empty collection of SourceDocTags containing the tags in this doc comment with the specified name.

findExceptionTags

java.util.Collection<SourceDocBlockTag> findExceptionTags()

Finds the @exception or @throws tags in this doc comment.

Returns:

a possibly empty collection of SourceDocBlockTags containing the @exception or @throws tags in this doc comment.

findExceptionTag

SourceDocBlockTag findExceptionTag(java.lang.String exceptionName)

Finds the first @exception or @throws tag in this doc comment with a specified fully-qualified name.

Returns:

the first @exception or @throws tag in this doc comment with a fully-qualified name of exceptionName, or null if none.

findParameterTag

SourceDocBlockTag findParameterTag(java.lang.String parameterName)

Finds the first @param tag in this doc comment with a specified name.

Returns:

the first @param tag in this doc comment with a name of parameterName, or null if none.

findReferenceTags

java.util.Collection<SourceDocTag> findReferenceTags()

Finds the @link, @linkplain, @see, and three-element @value tags in this doc comment.

Returns:

a possibly empty collection of SourceDocTags containing the @link, @linkplain, @see, and three-element @value tags in this doc comment.

findReferenceTags

java.util.Collection<SourceDocTag> findReferenceTags(java.lang.String referenceText)

Finds the @link, @linkplain, @see, and three-element @value tags in this doc comment with a specified normalized reference text.

Parameters:

referenceText - The normalized reference text to match.

Returns:

a possibly empty collection of SourceDocTags containing the @link, @linkplain, @see, or three-element @value tags in this doc comment with a normalized reference text equal to referenceText.