coalib.bearlib.languages.documentation package¶
Submodules¶
coalib.bearlib.languages.documentation.DocstyleDefinition module¶
-
class
coalib.bearlib.languages.documentation.DocstyleDefinition.
DocstyleDefinition
(*args, **kwargs)¶ Bases:
object
The DocstyleDefinition class holds values that identify a certain type of documentation comment (for which language, documentation style/tool used etc.).
-
docstyle
¶ The documentation style/tool used to document code.
Returns: A lower-case string defining the docstyle (i.e. “default” or “doxygen”).
-
language
¶ The programming language.
Returns: A lower-case string defining the programming language (i.e. “cpp” or “python”).
-
classmethod
load
(*args, **kwargs)¶
-
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.
-
coalib.bearlib.languages.documentation.DocumentationComment module¶
-
class
coalib.bearlib.languages.documentation.DocumentationComment.
DocumentationComment
(documentation, marker, range)¶ Bases:
object
The DocumentationComment holds information about a documentation comment inside source-code, like position etc.
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, markers)¶ 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).
- markers – The list/tuple of marker-sets that identify a documentation-comment. Low-index markers have higher priority than high-index markers.
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.