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.

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

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	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	findReferenceTags() Finds the @link, @linkplain, @see, and three-element @value tags in this doc comment.
java.util.Collection	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	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	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, clearBinding, cloneSelf, compile, getBinding, getChildren, getChildren, getCompiledObject, getContainedElements, getEndOffset, getOwningFile, getOwningSourceFile, getParent, getSiblingAfter, getSiblingBefore, getSiblings, getSiblings, getStartOffset, getSymbolKind, getText, 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 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 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 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 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 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.