Package de.gebit.integrity.utils

Class ParsedDocumentationComment

java.lang.Object

de.gebit.integrity.utils.ParsedDocumentationComment

public class ParsedDocumentationComment
extends java.lang.Object

The parsed version of a JavaDoc-style Integrity documentation comment.

Author:

Rene Schneider - initial API and implementation

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ParsedDocumentationComment.DocCommentElement	A single element of a documentation comment.
static class	ParsedDocumentationComment.DocCommentElementType	The supported types of elements in documentation comments.
static class	ParsedDocumentationComment.ParseException	These exceptions are thrown by the ParsedDocumentationComment constructors if parsing of a given DocumentationComment fails for whatever reason.

Field Summary

Fields

Modifier and Type	Field	Description
protected static java.lang.String	COMMENT_END	A documentation comment ends with this.
protected static java.lang.String	COMMENT_START	A documentation comment starts with this.
protected static java.util.regex.Pattern	DOC_COMMENT_TOKENIZER_PATTERN	The pattern used to split documentation comments into elements.
protected static java.lang.String	DOCUMENTATION_TAG_PARAMETER	The documentation tag for parameter descriptions.
protected static java.lang.String	DOCUMENTATION_TAG_RESULT	The documentation tag for result descriptions.
protected static java.lang.String	DOCUMENTATION_TAG_RETURN	The documentation tag for result descriptions.
protected static java.lang.String	DOCUMENTATION_TAG_START	The prefix that starts a documentation tag.
protected java.lang.String	documentationText	The core documentation text (non-parsed).
protected java.util.List<ParsedDocumentationComment.DocCommentElement>	documentationTextElements	The parsed core documentation text.
protected DocumentationComment	origin	The source element that this was parsed from.
protected java.util.Map<java.lang.String,java.lang.String>	parameterDocumentationTexts	Documentation for parameters (@param).
protected java.util.List<ParsedDocumentationComment.ParseException>	parseExceptions	Non-critical parse exceptions that were encountered while parsing the comment.
protected java.lang.String	rawText	The entire raw textual content (including @ elements, but excluding comment *s).
protected java.util.Map<java.lang.String,java.lang.String>	resultDocumentationTexts	Documentation for results (@result).
protected ModelSourceInformationElement	sourceInfo	Information about the source of the origin element.

Constructor Summary

Constructors

Constructor	Description
ParsedDocumentationComment(DocumentationComment aComment, ModelSourceInformationElement aModelSourceInfo)	Parses a given DocumentationComment and extracts the documentation info.
ParsedDocumentationComment(DocumentationComment aComment, ModelSourceInformationElement aModelSourceInfo, boolean anAllowUnnamedResultsFlag)	Parses a given DocumentationComment and extracts the documentation info.

Method Summary

Modifier and Type	Method	Description
protected static ModelSourceInformationElement	addLines(ModelSourceInformationElement anElement, int aNumberOfLines)	Clones the given ModelSourceInformationElement and adds a given number of lines to the line number of the provided element.
java.lang.String	getDocumentationText()
java.util.List<ParsedDocumentationComment.DocCommentElement>	getDocumentationTextElements()	Lazily calculates the documentation text elements and returns them.
java.lang.String	getJavadocStyleFullDocumentation()	Generates a representation of this entire documentation comments' content in Javadoc-style HTML.
DocumentationComment	getOrigin()
java.util.Map<java.lang.String,java.lang.String>	getParameterDocumentationTexts()
java.lang.String	getRawText()
java.util.Map<java.lang.String,java.lang.String>	getResultDocumentationTexts()
java.util.List<java.util.Map.Entry<java.lang.String,java.lang.String>>	getSortedParameterDocumentationTexts()
java.util.List<java.util.Map.Entry<java.lang.String,java.lang.String>>	getSortedResultDocumentationTexts()
ModelSourceInformationElement	getSourceInfo()
protected void	parse(java.lang.String aCommentString, ModelSourceInformationElement aModelSourceInfo, boolean anAllowUnnamedResultsFlag)	Actually performs the heavy lifting.
protected java.util.List<ParsedDocumentationComment.DocCommentElement>	tokenizeCommentText(java.lang.String aText)	Splits the documentation comment text into elements.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

origin

protected DocumentationComment origin

The source element that this was parsed from.

sourceInfo

protected ModelSourceInformationElement sourceInfo

Information about the source of the origin element.

parseExceptions

protected java.util.List<ParsedDocumentationComment.ParseException> parseExceptions

Non-critical parse exceptions that were encountered while parsing the comment. These exceptions did not result in an abortion of the parsing process, but point to problems nevertheless.

rawText

protected java.lang.String rawText

The entire raw textual content (including @ elements, but excluding comment *s).

documentationText

protected java.lang.String documentationText

The core documentation text (non-parsed).

documentationTextElements

protected java.util.List<ParsedDocumentationComment.DocCommentElement> documentationTextElements

The parsed core documentation text. May be empty if documentationText is empty.

parameterDocumentationTexts

protected java.util.Map<java.lang.String,java.lang.String> parameterDocumentationTexts

Documentation for parameters (@param).

resultDocumentationTexts

protected java.util.Map<java.lang.String,java.lang.String> resultDocumentationTexts

Documentation for results (@result). The one for the default result is added with key null.

COMMENT_START

protected static final java.lang.String COMMENT_START

A documentation comment starts with this.

See Also:

Constant Field Values

COMMENT_END

protected static final java.lang.String COMMENT_END

A documentation comment ends with this.

See Also:

Constant Field Values

DOCUMENTATION_TAG_START

protected static final java.lang.String DOCUMENTATION_TAG_START

The prefix that starts a documentation tag.

See Also:

Constant Field Values

DOCUMENTATION_TAG_PARAMETER

protected static final java.lang.String DOCUMENTATION_TAG_PARAMETER

The documentation tag for parameter descriptions.

See Also:

Constant Field Values

DOCUMENTATION_TAG_RESULT

protected static final java.lang.String DOCUMENTATION_TAG_RESULT

The documentation tag for result descriptions.

See Also:

Constant Field Values

DOCUMENTATION_TAG_RETURN

protected static final java.lang.String DOCUMENTATION_TAG_RETURN

The documentation tag for result descriptions. Can be used alternatively to DOCUMENTATION_TAG_RESULT.

See Also:

Constant Field Values

DOC_COMMENT_TOKENIZER_PATTERN

protected static final java.util.regex.Pattern DOC_COMMENT_TOKENIZER_PATTERN

The pattern used to split documentation comments into elements.

Constructor Detail

ParsedDocumentationComment

public ParsedDocumentationComment(DocumentationComment aComment,
                                  ModelSourceInformationElement aModelSourceInfo)
                           throws ParsedDocumentationComment.ParseException

Parses a given DocumentationComment and extracts the documentation info.

Parameters:

aComment - the comment element to be parsed

aModelSourceInfo - the information about the source of the element, if available

Throws:

ParsedDocumentationComment.ParseException - in case of parsing errors

ParsedDocumentationComment

public ParsedDocumentationComment(DocumentationComment aComment,
                                  ModelSourceInformationElement aModelSourceInfo,
                                  boolean anAllowUnnamedResultsFlag)
                           throws ParsedDocumentationComment.ParseException

Parses a given DocumentationComment and extracts the documentation info.

Parameters:

aComment - the comment element to be parsed

aModelSourceInfo - the information about the source of the element, if available

anAllowUnnamedResultsFlag - whether to apply a heuristic in determining if we have an unnamed result (false = all results named)

Throws:

ParsedDocumentationComment.ParseException - in case of parsing errors

Method Detail

parse

protected void parse(java.lang.String aCommentString,
                     ModelSourceInformationElement aModelSourceInfo,
                     boolean anAllowUnnamedResultsFlag)
              throws ParsedDocumentationComment.ParseException

Actually performs the heavy lifting.

Parameters:

aCommentString - the string to be parsed, right from the model element

aModelSourceInfo - the information about the source of the element, if available

anAllowUnnamedResultsFlag - whether to apply a heuristic in determining if we have an unnamed result (false = all results named)

Throws:

ParsedDocumentationComment.ParseException - in case of parsing errors

getOrigin

public DocumentationComment getOrigin()

getSourceInfo

public ModelSourceInformationElement getSourceInfo()

getRawText

public java.lang.String getRawText()

getDocumentationText

public java.lang.String getDocumentationText()

getDocumentationTextElements

public java.util.List<ParsedDocumentationComment.DocCommentElement> getDocumentationTextElements()

Lazily calculates the documentation text elements and returns them.

Returns:

getJavadocStyleFullDocumentation

public java.lang.String getJavadocStyleFullDocumentation()

Generates a representation of this entire documentation comments' content in Javadoc-style HTML. This includes all known @ elements.

Returns:

getParameterDocumentationTexts

public java.util.Map<java.lang.String,java.lang.String> getParameterDocumentationTexts()

getSortedParameterDocumentationTexts

public java.util.List<java.util.Map.Entry<java.lang.String,java.lang.String>> getSortedParameterDocumentationTexts()

getResultDocumentationTexts

public java.util.Map<java.lang.String,java.lang.String> getResultDocumentationTexts()

getSortedResultDocumentationTexts

public java.util.List<java.util.Map.Entry<java.lang.String,java.lang.String>> getSortedResultDocumentationTexts()

addLines

protected static final ModelSourceInformationElement addLines(ModelSourceInformationElement anElement,
                                                              int aNumberOfLines)

Clones the given ModelSourceInformationElement and adds a given number of lines to the line number of the provided element.

Parameters:

anElement - the base element

aNumberOfLines - the number of lines to add

Returns:

a clone with a changed line number

tokenizeCommentText

protected java.util.List<ParsedDocumentationComment.DocCommentElement> tokenizeCommentText(java.lang.String aText)

Splits the documentation comment text into elements.

Parameters:

aText -

Returns: