DocumentationComment.py: Accept position

DocumentationComment accept `position` instead
of `range` in `__init__`.
Cache `assemble()` to construct full `range`.
Amend tests to comply with changes.
Closes #2646

coalib/bearlib/languages/documentation/DocumentationComment.py

@@ -1,11 +1,13 @@
 from collections import namedtuple
 
 from coala_utils.decorators import generate_eq, generate_repr
+from coalib.results.TextRange import TextRange
+from functools import lru_cache
 
 
 @generate_repr()
 @generate_eq('documentation', 'language', 'docstyle',
-             'indent', 'marker', 'range')
+             'indent', 'marker', 'position')
 class DocumentationComment:
     """
     The DocumentationComment holds information about a documentation comment
@@ -17,7 +19,7 @@ class DocumentationComment:
     Description = namedtuple('Description', 'desc')
 
     def __init__(self, documentation, docstyle_definition,
-                 indent, marker, range):
+                 indent, marker, position):
         """
         Instantiates a new DocumentationComment.
 
@@ -32,14 +34,19 @@ def __init__(self, documentation, docstyle_definition,
         :param marker:
             The three-element tuple with marker strings, that identified this
             documentation comment.
-        :param range:
-            The position range of type ``TextRange``.
+        :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.range = range
+        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
@@ -182,7 +189,7 @@ def _parse_documentation_with_symbols(self,
 
     @classmethod
     def from_metadata(cls, doccomment, docstyle_definition,
-                      marker, indent, range):
+                      marker, indent, position):
         r"""
         Assembles a list of parsed documentation comment metadata.
 
@@ -193,7 +200,7 @@ def from_metadata(cls, doccomment, docstyle_definition,
         ...     import DocumentationComment
         >>> from coalib.bearlib.languages.documentation.DocstyleDefinition \
         ...     import DocstyleDefinition
-        >>> from coalib.results.TextRange import TextRange
+        >>> from coalib.results.TextPosition import TextPosition
         >>> Description = DocumentationComment.Description
         >>> Parameter = DocumentationComment.Parameter
         >>> python_default = DocstyleDefinition.load("python3", "default")
@@ -202,7 +209,7 @@ def from_metadata(cls, doccomment, docstyle_definition,
         >>> str(DocumentationComment.from_metadata(
         ...         parsed_doc, python_default,
         ...         python_default.markers[0], '    ',
-        ...         TextRange.from_values(0, 0, 0, 0)))
+        ...         TextPosition(0, 0)))
         '\nDescription\n:param age: Age\n'
 
         :param doccomment:
@@ -214,8 +221,8 @@ def from_metadata(cls, doccomment, docstyle_definition,
             The markers to be used in the documentation comment.
         :param indent:
             The indentation to be used in the documentation comment.
-        :param range:
-            The range of the documentation comment.
+        :param position:
+            The starting position of the documentation comment.
         :return:
             A ``DocumentationComment`` instance of the assembled documentation.
         """
@@ -239,8 +246,10 @@ def from_metadata(cls, doccomment, docstyle_definition,
             assembled_doc += ''.join(section_desc)
 
         return DocumentationComment(assembled_doc, docstyle_definition, indent,
-                                    marker, range)
+                                    marker, position)
 
+    # we need to cache this function so as to construct full `self.range`
+    @lru_cache(maxsize=1)
     def assemble(self):
         """
         Assembles parsed documentation to the original documentation.

coalib/bearlib/languages/documentation/DocumentationExtraction.py

@@ -4,7 +4,7 @@
     DocstyleDefinition)
 from coalib.bearlib.languages.documentation.DocumentationComment import (
     DocumentationComment)
-from coalib.results.TextRange import TextRange
+from coalib.results.TextPosition import TextPosition
 
 
 def _extract_doc_comment_simple(content, line, column, markers):
@@ -198,12 +198,9 @@ def _extract_doc_comment_from_line(content, line, column, regex,
             if doc_comment is not None:
                 end_line, end_column, documentation = doc_comment
 
-                rng = TextRange.from_values(line + 1,
-                                            len(indent) + 1,
-                                            end_line + 1,
-                                            end_column + 1)
+                position = TextPosition(line + 1, len(indent) + 1)
                 doc = DocumentationComment(documentation, docstyle_definition,
-                                           indent, marker, rng)
+                                           indent, marker, position)
 
                 return end_line, end_column, doc
 

tests/bearlib/languages/documentation/DocumentationCommentTest.py

@@ -8,6 +8,7 @@
     extract_documentation)
 from tests.bearlib.languages.documentation.TestUtils import (
     load_testdata)
+from coalib.results.TextPosition import TextPosition
 
 
 class DocumentationCommentTest(unittest.TestCase):
@@ -28,15 +29,15 @@ def test_fields(self):
                                    c_doxygen,
                                    ' ',
                                    ('/**', '*', '*/'),
-                                   (25, 45))
+                                   TextPosition(3, 1))
 
         self.assertEqual(uut.documentation, 'my doc')
         self.assertEqual(uut.language, 'c')
         self.assertEqual(uut.docstyle, 'doxygen')
         self.assertEqual(uut.indent, ' ')
         self.assertEqual(str(uut), 'my doc')
         self.assertEqual(uut.marker, ('/**', '*', '*/'))
-        self.assertEqual(uut.range, (25, 45))
+        self.assertEqual(uut.position, TextPosition(3, 1))
 
         python_doxygen = DocstyleDefinition.load('python', 'doxygen')
 
@@ -57,6 +58,7 @@ def test_fields(self):
         self.assertEqual(str(uut), 'qwertzuiop')
         self.assertEqual(uut.marker, ('##', '#', '#'))
         self.assertEqual(uut.range, None)
+        self.assertEqual(uut.position, None)
         self.assertEqual(uut.metadata, python_doxygen_metadata)
 
     def test_not_implemented(self):
@@ -72,7 +74,7 @@ def test_from_metadata(self):
 
         original = list(extract_documentation(data, 'python', 'default'))
 
-        parsed_docs = [(doc.parse(), doc.marker, doc.indent, doc.range)
+        parsed_docs = [(doc.parse(), doc.marker, doc.indent, doc.position)
                        for doc in original]
 
         docstyle_definition = DocstyleDefinition.load('python', 'default')

tests/bearlib/languages/documentation/DocumentationExtractionTest.py

@@ -8,7 +8,7 @@
     extract_documentation)
 from tests.bearlib.languages.documentation.TestUtils import (
     load_testdata)
-from coalib.results.TextRange import TextRange
+from coalib.results.TextPosition import TextPosition
 
 
 class DocumentationExtractionTest(unittest.TestCase):
@@ -33,7 +33,7 @@ def test_extract_documentation_C(self):
                                  ' @returns Your favorite number.\n'),
                                 docstyle_C_doxygen, '',
                                 docstyle_C_doxygen.markers[0],
-                                TextRange.from_values(3, 1, 7, 4)),
+                                TextPosition(3, 1)),
                             DocumentationComment(
                                 ('\n'
                                  ' Preserves alignment\n'
@@ -42,21 +42,21 @@ def test_extract_documentation_C(self):
                                  '     - sub sub item\n'),
                                 docstyle_C_doxygen, '',
                                 docstyle_C_doxygen.markers[2],
-                                TextRange.from_values(15, 1, 20, 4)),
+                                TextPosition(15, 1)),
                             DocumentationComment(
                                 (' ABC\n'
                                  '    Another type of comment\n'
                                  '\n'
                                  '    ...'),
                                 docstyle_C_doxygen, '',
                                 docstyle_C_doxygen.markers[1],
-                                TextRange.from_values(23, 1, 26, 11)),
+                                TextPosition(23, 1)),
                             DocumentationComment(
                                 (' foobar = barfoo.\n'
                                  ' @param x whatever...\n'),
                                 docstyle_C_doxygen, '',
                                 docstyle_C_doxygen.markers[0],
-                                TextRange.from_values(28, 1, 30, 4)))
+                                TextPosition(28, 1)))
 
         self.assertEqual(tuple(
             extract_documentation(data, 'C', 'doxygen')),
@@ -72,7 +72,7 @@ def test_extract_documentation_C_2(self):
             [DocumentationComment(' my main description\n continues here',
                                   docstyle_C_doxygen, '',
                                   docstyle_C_doxygen.markers[0],
-                                  TextRange.from_values(1, 1, 2, 21))])
+                                  TextPosition(1, 1))])
 
     def test_extract_documentation_CPP(self):
         data = load_testdata('data.cpp')
@@ -91,23 +91,23 @@ def test_extract_documentation_CPP(self):
                                '          Or any other number.\n'),
                               docstyle_CPP_doxygen, '',
                               docstyle_CPP_doxygen.markers[0],
-                              TextRange.from_values(4, 1, 8, 4)),
+                              TextPosition(4, 1)),
                           DocumentationComment(
                               (' foobar\n'
                                ' @param xyz\n'),
                               docstyle_CPP_doxygen, '',
                               docstyle_CPP_doxygen.markers[0],
-                              TextRange.from_values(15, 1, 17, 4)),
+                              TextPosition(15, 1)),
                           DocumentationComment(
                               ' Some alternate style of documentation\n',
                               docstyle_CPP_doxygen, '',
                               docstyle_CPP_doxygen.markers[4],
-                              TextRange.from_values(22, 1, 23, 1)),
+                              TextPosition(22, 1)),
                           DocumentationComment(
                               ' ends instantly',
                               docstyle_CPP_doxygen, '\t',
                               docstyle_CPP_doxygen.markers[0],
-                              TextRange.from_values(26, 2, 26, 23)),
+                              TextPosition(26, 2)),
                           DocumentationComment(
                               (' Should work\n'
                                '\n'
@@ -116,7 +116,7 @@ def test_extract_documentation_CPP(self):
                                ' @param foo WHAT PARAM PLEASE!?\n'),
                               docstyle_CPP_doxygen, '',
                               docstyle_CPP_doxygen.markers[4],
-                              TextRange.from_values(32, 1, 37, 1))))
+                              TextPosition(32, 1))))
 
     def test_extract_documentation_CPP_2(self):
         data = load_testdata('data2.cpp')
@@ -129,7 +129,7 @@ def test_extract_documentation_CPP_2(self):
                            ' hello world\n'),
                           docstyle_CPP_doxygen, '',
                           docstyle_CPP_doxygen.markers[0],
-                          TextRange.from_values(1, 1, 3, 4)),))
+                          TextPosition(1, 1)),))
 
     def test_extract_documentation_PYTHON3(self):
         data = load_testdata('data.py')
@@ -145,19 +145,19 @@ def test_extract_documentation_PYTHON3(self):
                          'Some more foobar-like text.\n'),
                         docstyle_PYTHON3_default, '',
                         docstyle_PYTHON3_default.markers[0],
-                        TextRange.from_values(1, 1, 5, 4)),
+                        TextPosition(1, 1)),
                     DocumentationComment(
                         ('\n'
                          'A nice and neat way of documenting code.\n'
                          ':param radius: The explosion radius.\n'),
                         docstyle_PYTHON3_default, ' ' * 4,
                         docstyle_PYTHON3_default.markers[0],
-                        TextRange.from_values(8, 5, 11, 8)),
+                        TextPosition(8, 5)),
                     DocumentationComment(
                         '\nA function that returns 55.\n',
                         docstyle_PYTHON3_default, ' ' * 8,
                         docstyle_PYTHON3_default.markers[0],
-                        TextRange.from_values(13, 9, 15, 12)),
+                        TextPosition(13, 9)),
                     DocumentationComment(
                         ('\n'
                          'Docstring with layouted text.\n'
@@ -167,28 +167,28 @@ def test_extract_documentation_PYTHON3(self):
                          'this is intended.\n'),
                         docstyle_PYTHON3_default, '',
                         docstyle_PYTHON3_default.markers[0],
-                        TextRange.from_values(19, 1, 24, 4)),
+                        TextPosition(19, 1)),
                     DocumentationComment(
                         (' Docstring directly besides triple quotes.\n'
                          '    Continues here. '),
                         docstyle_PYTHON3_default, '',
                         docstyle_PYTHON3_default.markers[0],
-                        TextRange.from_values(26, 1, 27, 24)),
+                        TextPosition(26, 1)),
                     DocumentationComment(
                         ('super\n'
                          ' nicely\n'
                          'short'),
                         docstyle_PYTHON3_default, '',
                         docstyle_PYTHON3_default.markers[0],
-                        TextRange.from_values(40, 1, 42, 9)),
+                        TextPosition(40, 1)),
                     DocumentationComment(
                         ('\n'
                          'A bad indented docstring\n'
                          '    Improper indentation.\n'
                          ':param impact: The force of Impact.\n'),
                         docstyle_PYTHON3_default, ' ' * 4,
                         docstyle_PYTHON3_default.markers[0],
-                        TextRange.from_values(45, 5, 49, 8)),
+                        TextPosition(45, 5)),
                     )
 
         self.assertEqual(
@@ -200,7 +200,7 @@ def test_extract_documentation_PYTHON3(self):
                                              docstyle_PYTHON3_doxygen,
                                              r.indent,
                                              r.marker,
-                                             r.range)
+                                             r.position)
                         for r in expected)
 
         expected.insert(5, DocumentationComment(
@@ -211,7 +211,7 @@ def test_extract_documentation_PYTHON3(self):
              '\n'),
             docstyle_PYTHON3_doxygen, '',
             docstyle_PYTHON3_doxygen.markers[1],
-            TextRange.from_values(30, 1, 35, 1)))
+            TextPosition(30, 1)))
 
         self.assertEqual(
             list(extract_documentation(data, 'PYTHON3', 'doxygen')),
@@ -228,7 +228,7 @@ def test_extract_documentation_PYTHON3_2(self):
             [DocumentationComment(' documentation in single line  ',
                                   docstyle_PYTHON3_default, '',
                                   docstyle_PYTHON3_default.markers[0],
-                                  TextRange.from_values(2, 1, 2, 38))])
+                                  TextPosition(2, 1))])
 
     def test_extract_documentation_PYTHON3_3(self):
         data = ['## documentation in single line without return at end.']
@@ -242,7 +242,7 @@ def test_extract_documentation_PYTHON3_3(self):
                                   'return at end.',
                                   docstyle_PYTHON3_doxygen, '',
                                   docstyle_PYTHON3_doxygen.markers[1],
-                                  TextRange.from_values(1, 1, 1, 55))])
+                                  TextPosition(1, 1))])
 
     def test_extract_documentation_PYTHON3_4(self):
         data = ['\n', 'triple_quote_string_test = """\n',