Package de.gebit.integrity.utils

## Class ParsedDocumentationComment

- java.lang.Object
- - de.gebit.integrity.utils.ParsedDocumentationComment

-     public class ParsedDocumentationComment
      extends 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 String` | `COMMENT_END` | A documentation comment ends with this.
    `protected static String` | `COMMENT_START` | A documentation comment starts with this.
    `protected static Pattern` | `DOC_COMMENT_TOKENIZER_PATTERN` | The pattern used to split documentation comments into elements.
    `protected static String` | `DOCUMENTATION_TAG_PARAMETER` | The documentation tag for parameter descriptions.
    `protected static String` | `DOCUMENTATION_TAG_RESULT` | The documentation tag for result descriptions.
    `protected static String` | `DOCUMENTATION_TAG_RETURN` | The documentation tag for result descriptions.
    `protected static String` | `DOCUMENTATION_TAG_START` | The prefix that starts a documentation tag.
    `protected String` | `documentationText` | The core documentation text (non-parsed).
    `protected List<ParsedDocumentationComment.DocCommentElement>` | `documentationTextElements` | The parsed core documentation text.
    `protected DocumentationComment` | `origin` | The source element that this was parsed from.
    `protected Map<String,​String>` | `parameterDocumentationTexts` | Documentation for parameters (@param).
    `protected List<ParsedDocumentationComment.ParseException>` | `parseExceptions` | Non-critical parse exceptions that were encountered while parsing the comment.
    `protected String` | `rawText` | The entire raw textual content (including @ elements, but excluding comment *s).
    `protected Map<String,​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

    All Methods Static Methods Instance Methods Concrete Methods
    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.
    `String` | `getDocumentationText()` |
    `List<ParsedDocumentationComment.DocCommentElement>` | `getDocumentationTextElements()` | Lazily calculates the documentation text elements and returns them.
    `String` | `getJavadocStyleFullDocumentation()` | Generates a representation of this entire documentation comments' content in Javadoc-style HTML.
    `DocumentationComment` | `getOrigin()` |
    `Map<String,​String>` | `getParameterDocumentationTexts()` |
    `String` | `getRawText()` |
    `Map<String,​String>` | `getResultDocumentationTexts()` |
    `List<Map.Entry<String,​String>>` | `getSortedParameterDocumentationTexts()` |
    `List<Map.Entry<String,​String>>` | `getSortedResultDocumentationTexts()` |
    `ModelSourceInformationElement` | `getSourceInfo()` |
    `protected void` | `parse​(String aCommentString, ModelSourceInformationElement aModelSourceInfo, boolean anAllowUnnamedResultsFlag)` | Actually performs the heavy lifting.
    `protected List<ParsedDocumentationComment.DocCommentElement>` | `tokenizeCommentText​(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 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 String rawText

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

    - #### documentationText

          protected String documentationText

      The core documentation text (non-parsed).

    - #### documentationTextElements

          protected List<ParsedDocumentationComment.DocCommentElement> documentationTextElements

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

    - #### parameterDocumentationTexts

          protected Map<String,​String> parameterDocumentationTexts

      Documentation for parameters (@param).

    - #### resultDocumentationTexts

          protected Map<String,​String> resultDocumentationTexts

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

    - #### COMMENT_START

          protected static final String COMMENT_START

      A documentation comment starts with this.
      See Also:
        Constant Field Values

    - #### COMMENT_END

          protected static final String COMMENT_END

      A documentation comment ends with this.
      See Also:
        Constant Field Values

    - #### DOCUMENTATION_TAG_START

          protected static final String DOCUMENTATION_TAG_START

      The prefix that starts a documentation tag.
      See Also:
        Constant Field Values

    - #### DOCUMENTATION_TAG_PARAMETER

          protected static final String DOCUMENTATION_TAG_PARAMETER

      The documentation tag for parameter descriptions.
      See Also:
        Constant Field Values

    - #### DOCUMENTATION_TAG_RESULT

          protected static final String DOCUMENTATION_TAG_RESULT

      The documentation tag for result descriptions.
      See Also:
        Constant Field Values

    - #### DOCUMENTATION_TAG_RETURN

          protected static final 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 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​(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 String getRawText()

    - #### getDocumentationText

          public String getDocumentationText()

    - #### getDocumentationTextElements

          public List<ParsedDocumentationComment.DocCommentElement> getDocumentationTextElements()

      Lazily calculates the documentation text elements and returns them.
      Returns:

    - #### getJavadocStyleFullDocumentation

          public String getJavadocStyleFullDocumentation()

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

    - #### getParameterDocumentationTexts

          public Map<String,​String> getParameterDocumentationTexts()

    - #### getSortedParameterDocumentationTexts

          public List<Map.Entry<String,​String>> getSortedParameterDocumentationTexts()

    - #### getResultDocumentationTexts

          public Map<String,​String> getResultDocumentationTexts()

    - #### getSortedResultDocumentationTexts

          public List<Map.Entry<String,​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 List<ParsedDocumentationComment.DocCommentElement> tokenizeCommentText​(String aText)

      Splits the documentation comment text into elements.
      Parameters:
        `aText` -
      Returns: