coalib.bearlib.languages.documentation package — coala 0.11.0.rc1 documentation

# coalib.bearlib.languages.documentation package

## Submodules

## coalib.bearlib.languages.documentation.DocstyleDefinition module

class `coalib.bearlib.languages.documentation.DocstyleDefinition.` `DocstyleDefinition`(language: str, docstyle: str, markers: (<class 'collections.abc.Iterable'>, <class 'str'>), metadata: coalib.bearlib.languages.documentation.DocstyleDefinition.Metadata)

  Bases: `object`

  The DocstyleDefinition class holds values that identify a certain type of documentation comment (for which language, documentation style/tool used etc.).

  class `Metadata`(param_start, param_end, return_sep)

    Bases: `tuple`

    `param_end`

      Alias for field number 1

    `param_start`

      Alias for field number 0

    `return_sep`

      Alias for field number 2

  `DocstyleDefinition.` `docstyle`

    The documentation style/tool used to document code.

    Returns: | A lower-case string defining the docstyle (i.e. “default” or “doxygen”).

  static `DocstyleDefinition.` `get_available_definitions`()

    Returns a sequence of pairs with `(docstyle, language)` which are available when using `load()`.

    Returns: | A sequence of pairs with `(docstyle, language)`.

  `DocstyleDefinition.` `language`

    The programming language.

    Returns: | A lower-case string defining the programming language (i.e. “cpp” or “python”).

  classmethod `DocstyleDefinition.` `load`(language: str, docstyle: str, coalang_dir=None)

    Loads a `DocstyleDefinition` from the coala docstyle definition files.

    This function considers all settings inside the according coalang-files as markers, except `param_start`, `param_end` and `return_sep` which are considered as special metadata markers.

    Note

    When placing new coala docstyle definition files, these must consist of only lowercase letters and end with `.coalang`!

    Parameters: | language – The case insensitive programming language of the documentation comment as a string. docstyle – The case insensitive documentation style/tool used to document code, e.g. `"default"` or `"doxygen"`. coalang_dir – Path to directory with coalang docstyle definition files. This replaces the default path if given.
    Raises: | FileNotFoundError – Raised when the given docstyle was not found. KeyError – Raised when the given language is not defined for given docstyle.
    Returns: | The `DocstyleDefinition` for given language and docstyle.

  `DocstyleDefinition.` `markers`

    A tuple of marker sets that identify a documentation comment.

    Marker sets consist of 3 entries where the first is the start-marker, the second one the each-line marker and the last one the end-marker. For example a marker tuple with a single marker set `(("/**", "*", "*/"),)` would match following documentation comment:

        /**
         * This is documentation.
         */

    It’s also possible to supply an empty each-line marker (`("/**", "", "*/")`):

        /**
         This is more documentation.
         */

    Markers are matched “greedy”, that means it will match as many each-line markers as possible. I.e. for `("///", "///", "///")`):

        /// Brief documentation.
        ///
        /// Detailed documentation.

    Returns: | A tuple of marker/delimiter string tuples that identify a documentation comment.

  `DocstyleDefinition.` `metadata`

    A namedtuple of certain attributes present in the documentation.

    These attributes are used to define parts of the documentation.

## coalib.bearlib.languages.documentation.DocumentationComment module

class `coalib.bearlib.languages.documentation.DocumentationComment.` `DocumentationComment`(documentation, docstyle_definition, indent, marker, range)

  Bases: `object`

  The DocumentationComment holds information about a documentation comment inside source-code, like position etc.

  class `Description`(desc)

    Bases: `tuple`

    `desc`

      Alias for field number 0

  class `DocumentationComment.` `Parameter`(name, desc)

    Bases: `tuple`

    `desc`

      Alias for field number 1

    `name`

      Alias for field number 0

  class `DocumentationComment.` `ReturnValue`(desc)

    Bases: `tuple`

    `desc`

      Alias for field number 0

  `DocumentationComment.` `assemble`()

    Assembles parsed documentation to the original documentation.

    This function assembles the whole documentation comment, with the given markers and indentation.

  `DocumentationComment.` `docstyle`
  classmethod `DocumentationComment.` `from_metadata`(doccomment, docstyle_definition, marker, indent, range)

    Assembles a list of parsed documentation comment metadata.

    This function just assembles the documentation comment itself, without the markers and indentation.

        >>> from coalib.bearlib.languages.documentation.DocumentationComment \
        ...     import DocumentationComment
        >>> from coalib.bearlib.languages.documentation.DocstyleDefinition \
        ...     import DocstyleDefinition
        >>> from coalib.results.TextRange import TextRange
        >>> Description = DocumentationComment.Description
        >>> Parameter = DocumentationComment.Parameter
        >>> python_default = DocstyleDefinition.load("python3", "default")
        >>> parsed_doc = [Description(desc='\nDescription\n'),
        ...               Parameter(name='age', desc=' Age\n')]
        >>> str(DocumentationComment.from_metadata(
        ...         parsed_doc, python_default,
        ...         python_default.markers[0], 4,
        ...         TextRange.from_values(0, 0, 0, 0)))
        '\nDescription\n:param age: Age\n'

    Parameters: | doccomment – The list of parsed documentation comment metadata. docstyle_definition – The `DocstyleDefinition` instance that defines what docstyle is being used in a documentation comment. marker – The markers to be used in the documentation comment. indent – The indentation to be used in the documentation comment. range – The range of the documentation comment.
    Returns: | A `DocumentationComment` instance of the assembled documentation.

  `DocumentationComment.` `language`
  `DocumentationComment.` `metadata`
  `DocumentationComment.` `parse`()

    Parses documentation independent of language and docstyle.

    Returns: | The list of all the parsed sections of the documentation. Every section is a namedtuple of either `Description` or `Parameter` or `ReturnValue`.
    Raises: | NotImplementedError – When no parsing method is present for the given language and docstyle.

## coalib.bearlib.languages.documentation.DocumentationExtraction module

`coalib.bearlib.languages.documentation.DocumentationExtraction.` `extract_documentation`(content, language, docstyle)

  Extracts all documentation texts inside the given source-code-string using the coala docstyle definition files.

  The documentation texts are sorted by their order appearing in `content`.

  For more information about how documentation comments are identified and extracted, see DocstyleDefinition.doctypes enumeration.

  Parameters: | content – The source-code-string where to extract documentation from. Needs to be a list or tuple where each string item is a single line (including ending whitespaces like `\n`). language – The programming language used. docstyle – The documentation style/tool used (e.g. doxygen).
  Raises: | FileNotFoundError – Raised when the docstyle definition file was not found. KeyError – Raised when the given language is not defined in given docstyle. ValueError – Raised when a docstyle definition setting has an invalid format.
  Returns: | An iterator returning each DocumentationComment found in the content.

`coalib.bearlib.languages.documentation.DocumentationExtraction.` `extract_documentation_with_markers`(content, docstyle_definition)

  Extracts all documentation texts inside the given source-code-string.

  Parameters: | content – The source-code-string where to extract documentation from. Needs to be a list or tuple where each string item is a single line (including ending whitespaces like `\n`). docstyle_definition – The `DocstyleDefinition` instance that defines what docstyle is being used in the documentation.
  Returns: | An iterator returning each DocumentationComment found in the content.

## Module contents

Provides facilities to extract, parse and assemble documentation comments for different languages and documentation tools.