Source code for coalib.bearlib.languages.documentation.DocBaseClass

from coalib.bearlib.languages.documentation.DocstyleDefinition import (
    DocstyleDefinition)
from coalib.results.Diff import Diff
from coalib.results.TextRange import TextRange
from coalib.bearlib.languages.documentation.DocumentationExtraction import (
    extract_documentation_with_markers)


[docs]class DocBaseClass: """ DocBaseClass holds important functions which will extract, parse and generates diffs for documentation. All bears that processes documentation should inherit from this. """
[docs] @staticmethod def extract(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. :param 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``). :param language: The programming language used. :param docstyle: The documentation style/tool used (e.g. doxygen). :raises FileNotFoundError: Raised when the docstyle definition file was not found. :raises KeyError: Raised when the given language is not defined in given docstyle. :raises ValueError: Raised when a docstyle definition setting has an invalid format. :return: An iterator returning instances of DocumentationComment or MalformedComment found in the content. """ docstyle_definition = DocstyleDefinition.load(language, docstyle) return extract_documentation_with_markers( content, docstyle_definition)
[docs] @staticmethod def generate_diff(file, doc_comment, new_comment): """ Generates diff between the original doc_comment and its fix new_comment which are instances of DocumentationComment. :param doc_comment: Original instance of DocumentationComment. :param new_comment: Fixed instance of DocumentationComment. :return: Diff instance. """ diff = Diff(file) # We need to update old comment positions, as `assemble()` # prepends indentation for first line. old_range = TextRange.from_values( doc_comment.range.start.line, 1, doc_comment.range.end.line, doc_comment.range.end.column) # Clearing cached assemble() so a fresh one is fetched. new_comment.assemble.cache_clear() diff.replace(old_range, new_comment.assemble()) return diff
[docs] def process_documentation(self, *args, **kwargs): """ Checks and handles the fixing part of documentation. :return: A tuple of processed documentation and warning_desc. """ raise NotImplementedError('This function has to be implemented for a ' 'documentation bear.')