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

from collections import namedtuple

from coala_utils.decorators import generate_eq, generate_repr
from coalib.results.TextRange import TextRange
from functools import lru_cache

    'Attribute': (':attr:`', '`'),
    'Class': (':class:`', '`'),
    'Constant': (':const:`', '`'),
    'Data': (':data:`', '`'),
    'Exception': (':exc:`', '`'),
    'Function': (':func:`', '`'),
    'Method': (':meth:`', '`'),
    'Module': (':mod:`', '`'),
    'Object': (':obj:`', '`')}

def _find_references(line, identifiers):
    Find references to another object in the given line.

    :param line:
        String to look into.
    :param identifiers:
        A dict mapping the type of references to a tuple of two strings with
        which the reference might start and end respectively.
        A list of two-element tuples containing the type of reference (inferred
        from the given dict) and the corresponding index of occurence in the
        line, sorted according to the index.
    occurences = []
    for ref_type, identifier in identifiers.items():
        ref = line.find(identifier[0])
        while ref != -1:
            occurences.append((ref_type, ref))
            ref = line.find(identifier[0], ref+1)
    return sorted(occurences, key=lambda x: x[1])

[docs]@generate_repr() @generate_eq('documentation', 'language', 'docstyle', 'indent', 'marker', 'position') class DocumentationComment: """ The DocumentationComment holds information about a documentation comment inside source-code, like position etc. """ Parameter = namedtuple('Parameter', 'name, desc') ExceptionValue = namedtuple('ExceptionValue', 'name, desc') ReturnValue = namedtuple('ReturnValue', 'desc') Description = namedtuple('Description', 'desc') Reference = namedtuple('Reference', ['type_ref', 'ref_addr']) top_padding = 0 bottom_padding = 0 docstring_type = 'others' def __init__(self, documentation, docstyle_definition, indent, marker, position): """ Instantiates a new DocumentationComment. :param documentation: The documentation text. :param docstyle_definition: The ``DocstyleDefinition`` instance that defines what docstyle is being used in the documentation. :param indent: The string of indentation used in front of the first marker of the documentation. :param marker: The three-element tuple with marker strings, that identified this documentation comment. :param position: The starting ``TextPosition`` of the documentation. """ self.documentation = documentation self.docstyle_definition = docstyle_definition self.indent = '' if indent is None else indent self.marker = ('', '', '') if marker is None else marker self.position = position self.range = None if position is None else TextRange.from_values( position.line, position.column, position.line + self.assemble().count('\n'), len(self.assemble()) - self.assemble().rfind('\n')) def __str__(self): return self.documentation @property def language(self): return self.docstyle_definition.language @property def docstyle(self): return self.docstyle_definition.docstyle @property def metadata(self): return self.docstyle_definition.metadata
[docs] def parse(self): """ Parses documentation independent of language and docstyle. :return: 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. """ if self.language == 'python' and self.docstyle == 'default': return self._parse_documentation_with_symbols( (':param ', ':'), (':raises ', ':'), ':return:', SPHINX_REF) elif self.language == 'python' and self.docstyle == 'doxygen': return self._parse_documentation_with_symbols( ('@param ', ' '), ('@raises ', ' '), '@return ') elif self.language == 'java' and self.docstyle == 'default': return self._parse_documentation_with_symbols( ('@param ', ' '), ('@raises ', ' '), '@return ') elif self.language == 'golang' and self.docstyle == 'golang': # golang does not have param, return markers return self.documentation.splitlines(keepends=True) else: raise NotImplementedError( 'Documentation parsing for {0.language!r} in {0.docstyle!r}' ' has not been implemented yet'.format(self))
def _parse_documentation_with_symbols(self, param_identifiers, exception_identifiers, return_identifiers, ref_identifiers={}): """ Parses documentation based on parameter, exception and return symbols. :param param_identifiers: A tuple of two strings with which a parameter starts and ends. :param exception_identifiers: A tuple of two strings with which an exception starts and ends. :param return_identifiers: The string with which a return description starts. :return: The list of all the parsed sections of the documentation. Every section is a named tuple of either ``Description``, ``Parameter``, ``ExceptionValue`` or ``ReturnValue``. """ lines = self.documentation.splitlines(keepends=True) parse_mode = self.Description cur_param = '' desc = '' parsed = [] for line in lines: stripped_line = line.strip() if stripped_line.startswith(param_identifiers[0]): parse_mode = self.Parameter # param_offset contains the starting column of param's name. param_offset = line.find( param_identifiers[0]) + len(param_identifiers[0]) # splitted contains the whole line from the param's name, # which in turn is further divided into its name and desc. splitted = line[param_offset:].split(param_identifiers[1], 1) # parser breaks if param_identifiers[1] is not present. # This checks for space and then splits the line accordingly # to extract param's name and desc. if len(splitted) == 1: splitted = line[param_offset:].split(' ', 1) cur_param = splitted[0].strip() param_desc = splitted[1] # parsed section is added to the final list. parsed.append(self.Parameter(name=cur_param, desc=param_desc)) elif stripped_line.startswith(exception_identifiers[0]): parse_mode = self.ExceptionValue exception_offset = line.find( exception_identifiers[0]) + len(exception_identifiers[0]) splitted = line[exception_offset:].split( exception_identifiers[1], 1) # parser breaks if exception_identifiers[1] is not present. # This checks for space and then splits the line accordingly # to extract exception's name and desc. if len(splitted) == 1: splitted = line[exception_offset:].split(' ', 1) cur_exception = splitted[0].strip() exception_desc = splitted[1] parsed.append(self.ExceptionValue( name=cur_exception, desc=exception_desc)) elif stripped_line.startswith(return_identifiers): parse_mode = self.ReturnValue return_offset = line.find( return_identifiers) + len(return_identifiers) retval_desc = line[return_offset:] parsed.append(self.ReturnValue(desc=retval_desc)) elif _find_references(line, ref_identifiers): occurences = _find_references(line, ref_identifiers) for ref, _ in occurences: identifier = ref_identifiers[ref] splitted = line.split(identifier[0], 1)[1].split( identifier[1], 1) addr = splitted[0].strip() line = splitted[1:][0] parsed.append(self.Reference(type_ref=ref, ref_addr=addr)) # These conditions will take care if the parsed section # descriptions are not on the same line as that of it's # name. Further, adding the parsed section to the final list. elif parse_mode == self.ReturnValue: retval_desc += line parsed.pop() parsed.append(self.ReturnValue(desc=retval_desc)) elif parse_mode == self.ExceptionValue: exception_desc += line parsed.pop() parsed.append(self.ExceptionValue( name=cur_exception, desc=exception_desc)) elif parse_mode == self.Parameter: param_desc += line parsed.pop() parsed.append(self.Parameter(name=cur_param, desc=param_desc)) else: desc += line # This is inside a try-except for cases where the list # is empty and has nothing to pop. try: parsed.pop() except IndexError: pass parsed.append(self.Description(desc=desc)) return parsed
[docs] @classmethod def from_metadata(cls, doccomment, docstyle_definition, marker, indent, position): r""" 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' :param doccomment: The list of parsed documentation comment metadata. :param docstyle_definition: The ``DocstyleDefinition`` instance that defines what docstyle is being used in a documentation comment. :param marker: The markers to be used in the documentation comment. :param indent: The indentation to be used in the documentation comment. :param position: The starting position of the documentation comment. :return: A ``DocumentationComment`` instance of the assembled documentation. """ assembled_doc = '' for section in doccomment: section_desc = section.desc.splitlines(keepends=True) if isinstance(section, cls.Parameter): assembled_doc += (docstyle_definition.metadata.param_start + + docstyle_definition.metadata.param_end) elif isinstance(section, cls.ExceptionValue): assembled_doc += (docstyle_definition.metadata.exception_start + + docstyle_definition.metadata.exception_end) elif isinstance(section, cls.ReturnValue): assembled_doc += docstyle_definition.metadata.return_sep assembled_doc += ''.join(section_desc) return DocumentationComment(assembled_doc, docstyle_definition, indent, marker, position)
# we need to cache this function so as to construct full `self.range`
[docs] @lru_cache(maxsize=1) def assemble(self): """ Assembles parsed documentation to the original documentation. This function assembles the whole documentation comment, with the given markers and indentation. """ lines = self.documentation.splitlines(keepends=True) assembled = self.indent + self.marker[0] if len(lines) == 0: return self.marker[0] + self.marker[2] assembled += lines[0] assembled += ''.join('\n' if line == '\n' and not self.marker[1] else self.indent + self.marker[1] + line for line in lines[1:]) assembled = (assembled if self.marker[1] == self.marker[2] else (assembled + (self.indent if lines[-1][-1] == '\n' else '') + self.marker[2])) assembled = ('\n' * self.top_padding + assembled + '\n' * self.bottom_padding) return assembled
[docs]class MalformedComment: """ 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. """ def __init__(self, message, line): """ Instantiate a MalformedComment, which contains the information about the error: a message explaining the behaviour and a line no where the error has occured. :param message: Contains the message about the error. :param line: Contains the current line number of the docstring where the error has occured. """ self.message = message self.line = line