coalib.bearlib.languages.documentation package¶
Submodules¶
coalib.bearlib.languages.documentation.DocBaseClass module¶
-
class
coalib.bearlib.languages.documentation.DocBaseClass.
DocBaseClass
[source]¶ Bases:
object
DocBaseClass holds important functions which will extract, parse and generates diffs for documentation. All bears that processes documentation should inherit from this.
-
static
extract
(content, language, docstyle)[source]¶ 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 instances of DocumentationComment or MalformedComment found in the content.
- 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
-
static
generate_diff
(file, doc_comment, new_comment)[source]¶ Generates diff between the original doc_comment and its fix new_comment which are instances of DocumentationComment.
Parameters: - doc_comment – Original instance of DocumentationComment.
- new_comment – Fixed instance of DocumentationComment.
Returns: Diff instance.
-
static
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, class_padding: coalib.bearlib.languages.documentation.DocstyleDefinition.ClassPadding, function_padding: coalib.bearlib.languages.documentation.DocstyleDefinition.FunctionPadding, docstring_type_regex: coalib.bearlib.languages.documentation.DocstyleDefinition.DocstringTypeRegex, docstring_position: str)[source]¶ Bases:
object
The DocstyleDefinition class holds values that identify a certain type of documentation comment (for which language, documentation style/tool used etc.).
-
class
ClassPadding
(top_padding, bottom_padding)¶ Bases:
tuple
-
bottom_padding
¶ Alias for field number 1
-
top_padding
¶ Alias for field number 0
-
-
class
DocstringTypeRegex
(class_sign, func_sign)¶ Bases:
tuple
-
class_sign
¶ Alias for field number 0
-
func_sign
¶ Alias for field number 1
-
-
class
FunctionPadding
(top_padding, bottom_padding)¶ Bases:
tuple
-
bottom_padding
¶ Alias for field number 1
-
top_padding
¶ Alias for field number 0
-
-
class
Metadata
(param_start, param_end, exception_start, exception_end, return_sep)¶ Bases:
tuple
-
exception_end
¶ Alias for field number 3
-
exception_start
¶ Alias for field number 2
-
param_end
¶ Alias for field number 1
-
param_start
¶ Alias for field number 0
-
return_sep
¶ Alias for field number 4
-
-
class_padding
¶ A namedtuple
ClassPadding
consisting of values about blank lines before and after the documentation ofdocstring_type
class.These values are official standard of following blank lines before and after the documentation of
docstring_type
class.
-
docstring_position
¶ Defines the position, where the regex of docstring type is present. Depending on different languages the docstrings are present below or above the defined class or function. This expicitly defines where the class regex or function regex is present(i.e.
top
orbottom
).
-
docstring_type_regex
¶ A namedtuple
DocstringTypeRegex
consisting of regex aboutclass
andfunction
of a language, which is used to determinedocstring_type
of DocumentationComment.
-
docstyle
¶ The documentation style/tool used to document code.
Returns: A lower-case string defining the docstyle (i.e. “default” or “doxygen”).
-
function_padding
¶ A namedtuple
FunctionPadding
consisting of values about blank lines before and after the documentation ofdocstring_type
function.These values are official standard of following blank lines before and after the documentation of
docstring_type
function.
-
static
get_available_definitions
()[source]¶ Returns a sequence of pairs with
(docstyle, language)
which are available when usingload()
.Returns: A sequence of pairs with (docstyle, language)
.
-
language
¶ The programming language.
Returns: A lower-case string defining the programming language (i.e. “cpp” or “python”).
-
classmethod
load
(language: str, docstyle: str, coalang_dir=None)[source]¶ 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
andreturn_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.
-
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.
-
metadata
¶ A namedtuple of certain attributes present in the documentation.
These attributes are used to define parts of the documentation.
-
class
coalib.bearlib.languages.documentation.DocumentationComment module¶
-
class
coalib.bearlib.languages.documentation.DocumentationComment.
DocumentationComment
(documentation, docstyle_definition, indent, marker, position)[source]¶ Bases:
object
The DocumentationComment holds information about a documentation comment inside source-code, like position etc.
-
class
ExceptionValue
(name, desc)¶ Bases:
tuple
-
desc
¶ Alias for field number 1
-
name
¶ Alias for field number 0
-
-
class
Parameter
(name, desc)¶ Bases:
tuple
-
desc
¶ Alias for field number 1
-
name
¶ Alias for field number 0
-
-
class
Reference
(type_ref, ref_addr)¶ Bases:
tuple
-
ref_addr
¶ Alias for field number 1
-
type_ref
¶ Alias for field number 0
-
-
assemble
[source]¶ Assembles parsed documentation to the original documentation.
This function assembles the whole documentation comment, with the given markers and indentation.
-
bottom_padding
= 0¶
-
docstring_type
= 'others'¶
-
docstyle
¶
-
classmethod
from_metadata
(doccomment, docstyle_definition, marker, indent, position)[source]¶ 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.TextPosition import TextPosition >>> 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], ' ', ... TextPosition(1, 1))) '\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.
- position – The starting position of the documentation comment.
Returns: A
DocumentationComment
instance of the assembled documentation.
-
language
¶
-
metadata
¶
-
parse
()[source]¶ 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
orParameter
orReturnValue
.Raises: NotImplementedError – When no parsing method is present for the given language and docstyle.
-
top_padding
= 0¶
-
class
-
class
coalib.bearlib.languages.documentation.DocumentationComment.
MalformedComment
(message, line)[source]¶ Bases:
object
The MalformedComment holds information about the errors generated by the DocumentationExtraction, DocumentationComment, DocstyleDefinition and DocBaseClass.
When these classes are unable to parse certain docstrings, an instance of MalformedComment will be returned instead of DocumentationComment.
coalib.bearlib.languages.documentation.DocumentationExtraction module¶
Language and docstyle independent extraction of documenation comments.
Each of the functions is built upon one another, and at the last,
exposes a single function extract_documentation_with_markers()
which is used by DocBaseClass
, to extract documentation.
-
coalib.bearlib.languages.documentation.DocumentationExtraction.
extract_documentation_with_markers
(content, docstyle_definition)[source]¶ 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.
- 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
Module contents¶
Provides facilities to extract, parse and assemble documentation comments for different languages and documentation tools.