Skip to content

Commit f3f613a

Browse files
damngamerzdamngamerz
committed
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
1 parent 526af97 commit f3f613a

File tree

4 files changed

+51
-43
lines changed

4 files changed

+51
-43
lines changed

‎coalib/bearlib/languages/documentation/DocumentationComment.py

Lines changed: 20 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
from collections import namedtuple
22

33
from coala_utils.decorators import generate_eq, generate_repr
4+
from coalib.results.TextRange import TextRange
5+
from functools import lru_cache
46

57

68
@generate_repr()
79
@generate_eq('documentation', 'language', 'docstyle',
8-
'indent', 'marker', 'range')
10+
'indent', 'marker', 'position')
911
class DocumentationComment:
1012
"""
1113
The DocumentationComment holds information about a documentation comment
@@ -17,7 +19,7 @@ class DocumentationComment:
1719
Description = namedtuple('Description', 'desc')
1820

1921
def __init__(self, documentation, docstyle_definition,
20-
indent, marker, range):
22+
indent, marker, position):
2123
"""
2224
Instantiates a new DocumentationComment.
2325
@@ -32,14 +34,19 @@ def __init__(self, documentation, docstyle_definition,
3234
:param marker:
3335
The three-element tuple with marker strings, that identified this
3436
documentation comment.
35-
:param range:
36-
The position range of type ``TextRange``.
37+
:param position:
38+
The starting ``TextPosition`` of the documentation.
3739
"""
3840
self.documentation = documentation
3941
self.docstyle_definition = docstyle_definition
4042
self.indent = '' if indent is None else indent
4143
self.marker = ('', '', '') if marker is None else marker
42-
self.range = range
44+
self.position = position
45+
self.range = None if position is None else TextRange.from_values(
46+
position.line,
47+
position.column,
48+
position.line + self.assemble().count('\n'),
49+
len(self.assemble()) - self.assemble().rfind('\n'))
4350

4451
def __str__(self):
4552
return self.documentation
@@ -182,7 +189,7 @@ def _parse_documentation_with_symbols(self,
182189

183190
@classmethod
184191
def from_metadata(cls, doccomment, docstyle_definition,
185-
marker, indent, range):
192+
marker, indent, position):
186193
r"""
187194
Assembles a list of parsed documentation comment metadata.
188195
@@ -193,7 +200,7 @@ def from_metadata(cls, doccomment, docstyle_definition,
193200
... import DocumentationComment
194201
>>> from coalib.bearlib.languages.documentation.DocstyleDefinition \
195202
... import DocstyleDefinition
196-
>>> from coalib.results.TextRange import TextRange
203+
>>> from coalib.results.TextPosition import TextPosition
197204
>>> Description = DocumentationComment.Description
198205
>>> Parameter = DocumentationComment.Parameter
199206
>>> python_default = DocstyleDefinition.load("python3", "default")
@@ -202,7 +209,7 @@ def from_metadata(cls, doccomment, docstyle_definition,
202209
>>> str(DocumentationComment.from_metadata(
203210
... parsed_doc, python_default,
204211
... python_default.markers[0], ' ',
205-
... TextRange.from_values(0, 0, 0, 0)))
212+
... TextPosition(0, 0)))
206213
'\nDescription\n:param age: Age\n'
207214
208215
:param doccomment:
@@ -214,8 +221,8 @@ def from_metadata(cls, doccomment, docstyle_definition,
214221
The markers to be used in the documentation comment.
215222
:param indent:
216223
The indentation to be used in the documentation comment.
217-
:param range:
218-
The range of the documentation comment.
224+
:param position:
225+
The starting position of the documentation comment.
219226
:return:
220227
A ``DocumentationComment`` instance of the assembled documentation.
221228
"""
@@ -239,8 +246,10 @@ def from_metadata(cls, doccomment, docstyle_definition,
239246
assembled_doc += ''.join(section_desc)
240247

241248
return DocumentationComment(assembled_doc, docstyle_definition, indent,
242-
marker, range)
249+
marker, position)
243250

251+
# we need to cache this function so as to construct full `self.range`
252+
@lru_cache(maxsize=1)
244253
def assemble(self):
245254
"""
246255
Assembles parsed documentation to the original documentation.

‎coalib/bearlib/languages/documentation/DocumentationExtraction.py

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
DocstyleDefinition)
55
from coalib.bearlib.languages.documentation.DocumentationComment import (
66
DocumentationComment)
7-
from coalib.results.TextRange import TextRange
7+
from coalib.results.TextPosition import TextPosition
88

99

1010
def _extract_doc_comment_simple(content, line, column, markers):
@@ -198,12 +198,9 @@ def _extract_doc_comment_from_line(content, line, column, regex,
198198
if doc_comment is not None:
199199
end_line, end_column, documentation = doc_comment
200200

201-
rng = TextRange.from_values(line + 1,
202-
len(indent) + 1,
203-
end_line + 1,
204-
end_column + 1)
201+
position = TextPosition(line + 1, len(indent) + 1)
205202
doc = DocumentationComment(documentation, docstyle_definition,
206-
indent, marker, rng)
203+
indent, marker, position)
207204

208205
return end_line, end_column, doc
209206

‎tests/bearlib/languages/documentation/DocumentationCommentTest.py

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
extract_documentation)
99
from tests.bearlib.languages.documentation.TestUtils import (
1010
load_testdata)
11+
from coalib.results.TextPosition import TextPosition
1112

1213

1314
class DocumentationCommentTest(unittest.TestCase):
@@ -28,15 +29,15 @@ def test_fields(self):
2829
c_doxygen,
2930
' ',
3031
('/**', '*', '*/'),
31-
(25, 45))
32+
TextPosition(3, 1))
3233

3334
self.assertEqual(uut.documentation, 'my doc')
3435
self.assertEqual(uut.language, 'c')
3536
self.assertEqual(uut.docstyle, 'doxygen')
3637
self.assertEqual(uut.indent, ' ')
3738
self.assertEqual(str(uut), 'my doc')
3839
self.assertEqual(uut.marker, ('/**', '*', '*/'))
39-
self.assertEqual(uut.range, (25, 45))
40+
self.assertEqual(uut.position, TextPosition(3, 1))
4041

4142
python_doxygen = DocstyleDefinition.load('python', 'doxygen')
4243

@@ -57,6 +58,7 @@ def test_fields(self):
5758
self.assertEqual(str(uut), 'qwertzuiop')
5859
self.assertEqual(uut.marker, ('##', '#', '#'))
5960
self.assertEqual(uut.range, None)
61+
self.assertEqual(uut.position, None)
6062
self.assertEqual(uut.metadata, python_doxygen_metadata)
6163

6264
def test_not_implemented(self):
@@ -72,7 +74,7 @@ def test_from_metadata(self):
7274

7375
original = list(extract_documentation(data, 'python', 'default'))
7476

75-
parsed_docs = [(doc.parse(), doc.marker, doc.indent, doc.range)
77+
parsed_docs = [(doc.parse(), doc.marker, doc.indent, doc.position)
7678
for doc in original]
7779

7880
docstyle_definition = DocstyleDefinition.load('python', 'default')

‎tests/bearlib/languages/documentation/DocumentationExtractionTest.py

Lines changed: 23 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
extract_documentation)
99
from tests.bearlib.languages.documentation.TestUtils import (
1010
load_testdata)
11-
from coalib.results.TextRange import TextRange
11+
from coalib.results.TextPosition import TextPosition
1212

1313

1414
class DocumentationExtractionTest(unittest.TestCase):
@@ -33,7 +33,7 @@ def test_extract_documentation_C(self):
3333
' @returns Your favorite number.\n'),
3434
docstyle_C_doxygen, '',
3535
docstyle_C_doxygen.markers[0],
36-
TextRange.from_values(3, 1, 7, 4)),
36+
TextPosition(3, 1)),
3737
DocumentationComment(
3838
('\n'
3939
' Preserves alignment\n'
@@ -42,21 +42,21 @@ def test_extract_documentation_C(self):
4242
' - sub sub item\n'),
4343
docstyle_C_doxygen, '',
4444
docstyle_C_doxygen.markers[2],
45-
TextRange.from_values(15, 1, 20, 4)),
45+
TextPosition(15, 1)),
4646
DocumentationComment(
4747
(' ABC\n'
4848
' Another type of comment\n'
4949
'\n'
5050
' ...'),
5151
docstyle_C_doxygen, '',
5252
docstyle_C_doxygen.markers[1],
53-
TextRange.from_values(23, 1, 26, 11)),
53+
TextPosition(23, 1)),
5454
DocumentationComment(
5555
(' foobar = barfoo.\n'
5656
' @param x whatever...\n'),
5757
docstyle_C_doxygen, '',
5858
docstyle_C_doxygen.markers[0],
59-
TextRange.from_values(28, 1, 30, 4)))
59+
TextPosition(28, 1)))
6060

6161
self.assertEqual(tuple(
6262
extract_documentation(data, 'C', 'doxygen')),
@@ -72,7 +72,7 @@ def test_extract_documentation_C_2(self):
7272
[DocumentationComment(' my main description\n continues here',
7373
docstyle_C_doxygen, '',
7474
docstyle_C_doxygen.markers[0],
75-
TextRange.from_values(1, 1, 2, 21))])
75+
TextPosition(1, 1))])
7676

7777
def test_extract_documentation_CPP(self):
7878
data = load_testdata('data.cpp')
@@ -91,23 +91,23 @@ def test_extract_documentation_CPP(self):
9191
' Or any other number.\n'),
9292
docstyle_CPP_doxygen, '',
9393
docstyle_CPP_doxygen.markers[0],
94-
TextRange.from_values(4, 1, 8, 4)),
94+
TextPosition(4, 1)),
9595
DocumentationComment(
9696
(' foobar\n'
9797
' @param xyz\n'),
9898
docstyle_CPP_doxygen, '',
9999
docstyle_CPP_doxygen.markers[0],
100-
TextRange.from_values(15, 1, 17, 4)),
100+
TextPosition(15, 1)),
101101
DocumentationComment(
102102
' Some alternate style of documentation\n',
103103
docstyle_CPP_doxygen, '',
104104
docstyle_CPP_doxygen.markers[4],
105-
TextRange.from_values(22, 1, 23, 1)),
105+
TextPosition(22, 1)),
106106
DocumentationComment(
107107
' ends instantly',
108108
docstyle_CPP_doxygen, '\t',
109109
docstyle_CPP_doxygen.markers[0],
110-
TextRange.from_values(26, 2, 26, 23)),
110+
TextPosition(26, 2)),
111111
DocumentationComment(
112112
(' Should work\n'
113113
'\n'
@@ -116,7 +116,7 @@ def test_extract_documentation_CPP(self):
116116
' @param foo WHAT PARAM PLEASE!?\n'),
117117
docstyle_CPP_doxygen, '',
118118
docstyle_CPP_doxygen.markers[4],
119-
TextRange.from_values(32, 1, 37, 1))))
119+
TextPosition(32, 1))))
120120

121121
def test_extract_documentation_CPP_2(self):
122122
data = load_testdata('data2.cpp')
@@ -129,7 +129,7 @@ def test_extract_documentation_CPP_2(self):
129129
' hello world\n'),
130130
docstyle_CPP_doxygen, '',
131131
docstyle_CPP_doxygen.markers[0],
132-
TextRange.from_values(1, 1, 3, 4)),))
132+
TextPosition(1, 1)),))
133133

134134
def test_extract_documentation_PYTHON3(self):
135135
data = load_testdata('data.py')
@@ -145,19 +145,19 @@ def test_extract_documentation_PYTHON3(self):
145145
'Some more foobar-like text.\n'),
146146
docstyle_PYTHON3_default, '',
147147
docstyle_PYTHON3_default.markers[0],
148-
TextRange.from_values(1, 1, 5, 4)),
148+
TextPosition(1, 1)),
149149
DocumentationComment(
150150
('\n'
151151
'A nice and neat way of documenting code.\n'
152152
':param radius: The explosion radius.\n'),
153153
docstyle_PYTHON3_default, ' ' * 4,
154154
docstyle_PYTHON3_default.markers[0],
155-
TextRange.from_values(8, 5, 11, 8)),
155+
TextPosition(8, 5)),
156156
DocumentationComment(
157157
'\nA function that returns 55.\n',
158158
docstyle_PYTHON3_default, ' ' * 8,
159159
docstyle_PYTHON3_default.markers[0],
160-
TextRange.from_values(13, 9, 15, 12)),
160+
TextPosition(13, 9)),
161161
DocumentationComment(
162162
('\n'
163163
'Docstring with layouted text.\n'
@@ -167,28 +167,28 @@ def test_extract_documentation_PYTHON3(self):
167167
'this is intended.\n'),
168168
docstyle_PYTHON3_default, '',
169169
docstyle_PYTHON3_default.markers[0],
170-
TextRange.from_values(19, 1, 24, 4)),
170+
TextPosition(19, 1)),
171171
DocumentationComment(
172172
(' Docstring directly besides triple quotes.\n'
173173
' Continues here. '),
174174
docstyle_PYTHON3_default, '',
175175
docstyle_PYTHON3_default.markers[0],
176-
TextRange.from_values(26, 1, 27, 24)),
176+
TextPosition(26, 1)),
177177
DocumentationComment(
178178
('super\n'
179179
' nicely\n'
180180
'short'),
181181
docstyle_PYTHON3_default, '',
182182
docstyle_PYTHON3_default.markers[0],
183-
TextRange.from_values(40, 1, 42, 9)),
183+
TextPosition(40, 1)),
184184
DocumentationComment(
185185
('\n'
186186
'A bad indented docstring\n'
187187
' Improper indentation.\n'
188188
':param impact: The force of Impact.\n'),
189189
docstyle_PYTHON3_default, ' ' * 4,
190190
docstyle_PYTHON3_default.markers[0],
191-
TextRange.from_values(45, 5, 49, 8)),
191+
TextPosition(45, 5)),
192192
)
193193

194194
self.assertEqual(
@@ -200,7 +200,7 @@ def test_extract_documentation_PYTHON3(self):
200200
docstyle_PYTHON3_doxygen,
201201
r.indent,
202202
r.marker,
203-
r.range)
203+
r.position)
204204
for r in expected)
205205

206206
expected.insert(5, DocumentationComment(
@@ -211,7 +211,7 @@ def test_extract_documentation_PYTHON3(self):
211211
'\n'),
212212
docstyle_PYTHON3_doxygen, '',
213213
docstyle_PYTHON3_doxygen.markers[1],
214-
TextRange.from_values(30, 1, 35, 1)))
214+
TextPosition(30, 1)))
215215

216216
self.assertEqual(
217217
list(extract_documentation(data, 'PYTHON3', 'doxygen')),
@@ -228,7 +228,7 @@ def test_extract_documentation_PYTHON3_2(self):
228228
[DocumentationComment(' documentation in single line ',
229229
docstyle_PYTHON3_default, '',
230230
docstyle_PYTHON3_default.markers[0],
231-
TextRange.from_values(2, 1, 2, 38))])
231+
TextPosition(2, 1))])
232232

233233
def test_extract_documentation_PYTHON3_3(self):
234234
data = ['## documentation in single line without return at end.']
@@ -242,7 +242,7 @@ def test_extract_documentation_PYTHON3_3(self):
242242
'return at end.',
243243
docstyle_PYTHON3_doxygen, '',
244244
docstyle_PYTHON3_doxygen.markers[1],
245-
TextRange.from_values(1, 1, 1, 55))])
245+
TextPosition(1, 1))])
246246

247247
def test_extract_documentation_PYTHON3_4(self):
248248
data = ['\n', 'triple_quote_string_test = """\n',

0 commit comments

Comments
 (0)