Skip to content

Commit

Permalink
DocumentationComment: Add language, docstyle param
Browse files Browse the repository at this point in the history 
The docstyle and language is needed for language independent
documentation extraction.
  • Loading branch information
@SanketDG
SanketDG committed Jun 18, 2016
1 parent eacf74e commit 56e1802
Show file tree
Hide file tree
Showing 4 changed files with 54 additions and 16 deletions.
12 changes: 8 additions & 4 deletions coalib/bearlib/languages/documentation/DocumentationComment.py
View file
Expand Up @@ -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

Expand Down
15 changes: 10 additions & 5 deletions coalib/bearlib/languages/documentation/DocumentationExtraction.py
View file
Expand Up @@ -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()
Expand All @@ -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.
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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 changes: 8 additions & 0 deletions tests/bearlib/languages/documentation/DocumentationCommentTest.py
View file
Expand Up @@ -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)
35 changes: 28 additions & 7 deletions tests/bearlib/languages/documentation/DocumentationExtractionTest.py
View file
Expand Up @@ -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(
Expand All @@ -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 */']
Expand All @@ -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))])

Expand All @@ -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(
Expand All @@ -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))))

Expand All @@ -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",
Expand All @@ -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(
Expand All @@ -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)))

Expand All @@ -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)
Expand All @@ -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)))

Expand All @@ -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))])

Expand All @@ -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.