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.