Permalink
Browse files

DocumentationComment: Add language, docstyle param

The docstyle and language is needed for language independent
documentation extraction.
  • Loading branch information...
SanketDG committed May 17, 2016
1 parent eacf74e commit 56e180254ad37c33593e851a7e4bcb406964ab81
@@ -2,23 +2,27 @@
@generate_repr()
@generate_eq("documentation", "marker", "range")
@generate_eq("documentation", "language", "docstyle", "marker", "range")
class DocumentationComment:
"""
The DocumentationComment holds information about a documentation comment
inside source-code, like position etc.
"""
def __init__(self, documentation, marker, range):
def __init__(self, documentation, language, docstyle, marker, range):
"""
Instantiates a new DocumentationComment.
:param documentation: The documentation text.
:param marker: The three-element tuple with marker strings that
identified this documentation comment.
:param language: The language of the documention.
:param docstyle: The docstyle used in the documentation.
:param marker: The three-element tuple with marker strings,
that identified this documentation comment.
:param range: The position range of type TextRange.
"""
self.documentation = documentation
self.language = language.lower()
self.docstyle = docstyle.lower()
self.marker = marker
self.range = range
@@ -181,7 +181,8 @@ def _compile_multi_match_regex(strings):
return re.compile("|".join(re.escape(s) for s in strings))
def _extract_doc_comment_from_line(content, line, column, regex, marker_dict):
def _extract_doc_comment_from_line(content, line, column, regex,
marker_dict, language, docstyle):
begin_match = regex.search(content[line], column)
if begin_match:
column = begin_match.end()
@@ -194,14 +195,15 @@ def _extract_doc_comment_from_line(content, line, column, regex, marker_dict):
begin_match.start() + 1,
end_line + 1,
end_column + 1)
doc = DocumentationComment(documentation, marker, rng)
doc = DocumentationComment(documentation, language,
docstyle, marker, rng)
return end_line, end_column, doc
return line + 1, 0, None
def extract_documentation_with_markers(content, markers):
def extract_documentation_with_markers(content, markers, language, docstyle):
"""
Extracts all documentation texts inside the given source-code-string.
@@ -238,7 +240,9 @@ def extract_documentation_with_markers(content, markers):
line,
column,
begin_regex,
marker_dict)
marker_dict,
language,
docstyle)
if doc:
yield doc
@@ -271,4 +275,5 @@ def extract_documentation(content, language, docstyle):
"""
docstyle_definition = DocstyleDefinition.load(language, docstyle)
return extract_documentation_with_markers(content,
docstyle_definition.markers)
docstyle_definition.markers,
language, docstyle)
@@ -8,19 +8,27 @@ class DocumentationCommentTest(unittest.TestCase):
def test_fields(self):
uut = DocumentationComment("my doc",
"c",
"default",
("/**", "*", "*/"),
(25, 45))
self.assertEqual(uut.documentation, "my doc")
self.assertEqual(uut.language, "c")
self.assertEqual(uut.docstyle, "default")
self.assertEqual(str(uut), "my doc")
self.assertEqual(uut.marker, ("/**", "*", "*/"))
self.assertEqual(uut.range, (25, 45))
uut = DocumentationComment("qwertzuiop",
"python",
"doxygen",
("##", "#", "#"),
None)
self.assertEqual(uut.documentation, "qwertzuiop")
self.assertEqual(uut.language, "python")
self.assertEqual(uut.docstyle, "doxygen")
self.assertEqual(str(uut), "qwertzuiop")
self.assertEqual(uut.marker, ("##", "#", "#"))
self.assertEqual(uut.range, None)
@@ -39,6 +39,7 @@ def test_extract_documentation_C(self):
" This is the main function.\n"
"\n"
" @returns Your favorite number.\n"),
"C", "doxygen",
docstyle_C_doxygen.markers[0],
TextRange.from_values(3, 1, 7, 4)),
DocumentationComment(
@@ -47,23 +48,27 @@ def test_extract_documentation_C(self):
" - Main item\n"
" - sub item\n"
" - sub sub item\n"),
"C", "doxygen",
docstyle_C_doxygen.markers[2],
TextRange.from_values(15, 1, 20, 4)),
DocumentationComment(
(" ABC\n"
" Another type of comment\n"
"\n"
" ..."),
"C", "doxygen",
docstyle_C_doxygen.markers[1],
TextRange.from_values(23, 1, 26, 11)),
DocumentationComment(
(" foobar = barfoo.\n"
" @param x whatever...\n"),
"C", "doxygen",
docstyle_C_doxygen.markers[0],
TextRange.from_values(28, 1, 30, 4)))
self.assertEqual(tuple(extract_documentation(data, "C", "doxygen")),
expected_results)
self.assertEqual(tuple(
extract_documentation(data, "C", "doxygen")),
expected_results)
def test_extract_documentation_C_2(self):
data = ['/** my main description\n', ' * continues here */']
@@ -73,6 +78,7 @@ def test_extract_documentation_C_2(self):
self.assertEqual(
list(extract_documentation(data, "C", "doxygen")),
[DocumentationComment(" my main description\n continues here",
"C", "doxygen",
docstyle_C_doxygen.markers[0],
TextRange.from_values(1, 1, 2, 21))])
@@ -91,19 +97,23 @@ def test_extract_documentation_CPP(self):
" This is the main function.\n"
" @returns Exit code.\n"
" Or any other number.\n"),
"CPP", "doxygen",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(4, 1, 8, 4)),
DocumentationComment(
(" foobar\n"
" @param xyz\n"),
"CPP", "doxygen",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(15, 1, 17, 4)),
DocumentationComment(
" Some alternate style of documentation\n",
"CPP", "doxygen",
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(22, 1, 23, 1)),
DocumentationComment(
" ends instantly",
"CPP", "doxygen",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(26, 5, 26, 26)),
DocumentationComment(
@@ -112,6 +122,7 @@ def test_extract_documentation_CPP(self):
" even without a function standing below.\n"
"\n"
" @param foo WHAT PARAM PLEASE!?\n"),
"CPP", "doxygen",
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(32, 1, 37, 1))))
@@ -122,14 +133,14 @@ def test_extract_documentation_CPP_2(self):
self.assertEqual(tuple(extract_documentation(data, "CPP", "doxygen")),
(DocumentationComment(
("module comment\n"
" hello world\n"),
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(1, 1, 3, 4)),))
("module comment\n"
" hello world\n"),
"CPP", "doxygen",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(1, 1, 3, 4)),))
def test_extract_documentation_PYTHON3(self):
data = DocumentationExtractionTest.load_testdata("data.py")
docstyle_PYTHON3_default = DocstyleDefinition.load("PYTHON3",
"default")
docstyle_PYTHON3_doxygen = DocstyleDefinition.load("PYTHON3",
@@ -140,12 +151,14 @@ def test_extract_documentation_PYTHON3(self):
"Module description.\n"
"\n"
"Some more foobar-like text.\n"),
"PYTHON3", "default",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(1, 1, 5, 4)),
DocumentationComment(
("\n"
"A nice and neat way of documenting code.\n"
":param radius: The explosion radius.\n"),
"PYTHON3", "default",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(8, 5, 11, 8)),
DocumentationComment(
@@ -155,17 +168,20 @@ def test_extract_documentation_PYTHON3(self):
" layouts inside docs are preserved for these "
"documentation styles.\n"
"this is intended.\n"),
"PYTHON3", "default",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(14, 1, 19, 4)),
DocumentationComment(
(" Docstring directly besides triple quotes.\n"
" Continues here. "),
"PYTHON3", "default",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(21, 1, 22, 24)),
DocumentationComment(
("super\n"
" nicely\n"
"short"),
"PYTHON3", "default",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(35, 1, 37, 9)))
@@ -175,6 +191,8 @@ def test_extract_documentation_PYTHON3(self):
# Change only the docstyle in expected results.
expected = list(DocumentationComment(r.documentation,
r.language,
"doxygen",
r.marker,
r.range)
for r in expected)
@@ -185,6 +203,7 @@ def test_extract_documentation_PYTHON3(self):
" More subtext (not correctly aligned)\n"
" sub-sub-text\n"
"\n"),
"PYTHON3", "doxygen",
docstyle_PYTHON3_doxygen.markers[1],
TextRange.from_values(25, 1, 30, 1)))
@@ -201,6 +220,7 @@ def test_extract_documentation_PYTHON3_2(self):
self.assertEqual(
list(extract_documentation(data, "PYTHON3", "default")),
[DocumentationComment(" documentation in single line ",
"PYTHON3", "default",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(2, 1, 2, 38))])
@@ -214,5 +234,6 @@ def test_extract_documentation_PYTHON3_3(self):
list(extract_documentation(data, "PYTHON3", "doxygen")),
[DocumentationComment(" documentation in single line without "
"return at end.",
"PYTHON3", "doxygen",
docstyle_PYTHON3_doxygen.markers[1],
TextRange.from_values(1, 1, 1, 55))])

0 comments on commit 56e1802

Please sign in to comment.