Skip to content

/ coala

Permalink
Browse files
Loading status checks…

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
  • Loading branch information
@damngamerz
damngamerz committed Jun 25, 2017
1 parent 526af97 commit f3f613a705aedf132ac479dfe759c94e78969593
31 coalib/bearlib/languages/documentation/DocumentationComment.py
View file
@@ -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.
9 coalib/bearlib/languages/documentation/DocumentationExtraction.py
View file
@@ -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

8 tests/bearlib/languages/documentation/DocumentationCommentTest.py
View file
@@ -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')
46 tests/bearlib/languages/documentation/DocumentationExtractionTest.py
View file
@@ -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',

0 comments on commit f3f613a

Please sign in to comment.
You can’t perform that action at this time.