Skip to content

Commit

Permalink
DocumentationComment: Add indent param
Browse files Browse the repository at this point in the history 
To store the indentation level in spaces of a certain
documentation comment.
  • Loading branch information
@SanketDG
SanketDG committed Jun 18, 2016
1 parent 56e1802 commit 72b6c9c
Show file tree
Hide file tree
Showing 6 changed files with 53 additions and 31 deletions.
9 changes: 7 additions & 2 deletions coalib/bearlib/languages/documentation/DocumentationComment.py
View file
Expand Up @@ -2,27 +2,32 @@


@generate_repr()
@generate_eq("documentation", "language", "docstyle", "marker", "range")
@generate_eq("documentation", "language", "docstyle",
"indent", "marker", "range")
class DocumentationComment:
"""
The DocumentationComment holds information about a documentation comment
inside source-code, like position etc.
"""

def __init__(self, documentation, language, docstyle, marker, range):
def __init__(self, documentation, language,
docstyle, indent, marker, range):
"""
Instantiates a new DocumentationComment.
:param documentation: The documentation text.
:param language: The language of the documention.
:param docstyle: The docstyle used in the documentation.
:param indent: The string of indentation used in front
of the first marker of 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.indent = indent
self.marker = marker
self.range = range

Expand Down
6 changes: 4 additions & 2 deletions coalib/bearlib/languages/documentation/DocumentationExtraction.py
View file
Expand Up @@ -183,8 +183,10 @@ def _compile_multi_match_regex(strings):

def _extract_doc_comment_from_line(content, line, column, regex,
marker_dict, language, docstyle):
begin_match = regex.search(content[line], column)
cur_line = content[line]
begin_match = regex.search(cur_line, column)
if begin_match:
indent = cur_line[:begin_match.start()]
column = begin_match.end()
for marker in marker_dict[begin_match.group()]:
doc_comment = _extract_doc_comment(content, line, column, marker)
Expand All @@ -196,7 +198,7 @@ def _extract_doc_comment_from_line(content, line, column, regex,
end_line + 1,
end_column + 1)
doc = DocumentationComment(documentation, language,
docstyle, marker, rng)
docstyle, indent, marker, rng)

return end_line, end_column, doc

Expand Down
4 changes: 4 additions & 0 deletions tests/bearlib/languages/documentation/DocumentationCommentTest.py
View file
Expand Up @@ -10,25 +10,29 @@ 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(uut.indent, " ")
self.assertEqual(str(uut), "my doc")
self.assertEqual(uut.marker, ("/**", "*", "*/"))
self.assertEqual(uut.range, (25, 45))

uut = DocumentationComment("qwertzuiop",
"python",
"doxygen",
"\t",
("##", "#", "#"),
None)

self.assertEqual(uut.documentation, "qwertzuiop")
self.assertEqual(uut.language, "python")
self.assertEqual(uut.docstyle, "doxygen")
self.assertEqual(uut.indent, "\t")
self.assertEqual(str(uut), "qwertzuiop")
self.assertEqual(uut.marker, ("##", "#", "#"))
self.assertEqual(uut.range, None)
56 changes: 31 additions & 25 deletions tests/bearlib/languages/documentation/DocumentationExtractionTest.py
View file
Expand Up @@ -39,7 +39,7 @@ def test_extract_documentation_C(self):
" This is the main function.\n"
"\n"
" @returns Your favorite number.\n"),
"C", "doxygen",
"C", "doxygen", "",
docstyle_C_doxygen.markers[0],
TextRange.from_values(3, 1, 7, 4)),
DocumentationComment(
Expand All @@ -48,21 +48,21 @@ def test_extract_documentation_C(self):
" - Main item\n"
" - sub item\n"
" - sub sub item\n"),
"C", "doxygen",
"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",
"C", "doxygen", "",
docstyle_C_doxygen.markers[1],
TextRange.from_values(23, 1, 26, 11)),
DocumentationComment(
(" foobar = barfoo.\n"
" @param x whatever...\n"),
"C", "doxygen",
"C", "doxygen", "",
docstyle_C_doxygen.markers[0],
TextRange.from_values(28, 1, 30, 4)))

Expand All @@ -78,7 +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",
"C", "doxygen", "",
docstyle_C_doxygen.markers[0],
TextRange.from_values(1, 1, 2, 21))])

Expand All @@ -97,32 +97,32 @@ def test_extract_documentation_CPP(self):
" This is the main function.\n"
" @returns Exit code.\n"
" Or any other number.\n"),
"CPP", "doxygen",
"CPP", "doxygen", "",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(4, 1, 8, 4)),
DocumentationComment(
(" foobar\n"
" @param xyz\n"),
"CPP", "doxygen",
"CPP", "doxygen", "",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(15, 1, 17, 4)),
DocumentationComment(
" Some alternate style of documentation\n",
"CPP", "doxygen",
"CPP", "doxygen", "",
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(22, 1, 23, 1)),
DocumentationComment(
" ends instantly",
"CPP", "doxygen",
"CPP", "doxygen", "\t",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(26, 5, 26, 26)),
TextRange.from_values(26, 2, 26, 23)),
DocumentationComment(
(" Should work\n"
"\n"
" even without a function standing below.\n"
"\n"
" @param foo WHAT PARAM PLEASE!?\n"),
"CPP", "doxygen",
"CPP", "doxygen", "",
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(32, 1, 37, 1))))

Expand All @@ -135,7 +135,7 @@ def test_extract_documentation_CPP_2(self):
(DocumentationComment(
("module comment\n"
" hello world\n"),
"CPP", "doxygen",
"CPP", "doxygen", "",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(1, 1, 3, 4)),))

Expand All @@ -151,39 +151,44 @@ def test_extract_documentation_PYTHON3(self):
"Module description.\n"
"\n"
"Some more foobar-like text.\n"),
"PYTHON3", "default",
"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",
"PYTHON3", "default", " " * 4,
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(8, 5, 11, 8)),
DocumentationComment(
"\nA function that returns 55.\n",
"PYTHON3", "default", " " * 8,
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(13, 9, 15, 12)),
DocumentationComment(
("\n"
"Docstring with layouted text.\n"
"\n"
" layouts inside docs are preserved for these "
"documentation styles.\n"
"this is intended.\n"),
"PYTHON3", "default",
"PYTHON3", "default", "",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(14, 1, 19, 4)),
TextRange.from_values(19, 1, 24, 4)),
DocumentationComment(
(" Docstring directly besides triple quotes.\n"
" Continues here. "),
"PYTHON3", "default",
"PYTHON3", "default", "",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(21, 1, 22, 24)),
TextRange.from_values(26, 1, 27, 24)),
DocumentationComment(
("super\n"
" nicely\n"
"short"),
"PYTHON3", "default",
"PYTHON3", "default", "",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(35, 1, 37, 9)))
TextRange.from_values(40, 1, 42, 9)))

self.assertEqual(
tuple(extract_documentation(data, "PYTHON3", "default")),
Expand All @@ -193,19 +198,20 @@ def test_extract_documentation_PYTHON3(self):
expected = list(DocumentationComment(r.documentation,
r.language,
"doxygen",
r.indent,
r.marker,
r.range)
for r in expected)

expected.insert(4, DocumentationComment(
expected.insert(5, DocumentationComment(
(" Alternate documentation style in doxygen.\n"
" Subtext\n"
" More subtext (not correctly aligned)\n"
" sub-sub-text\n"
"\n"),
"PYTHON3", "doxygen",
"PYTHON3", "doxygen", "",
docstyle_PYTHON3_doxygen.markers[1],
TextRange.from_values(25, 1, 30, 1)))
TextRange.from_values(30, 1, 35, 1)))

self.assertEqual(
list(extract_documentation(data, "PYTHON3", "doxygen")),
Expand All @@ -220,7 +226,7 @@ def test_extract_documentation_PYTHON3_2(self):
self.assertEqual(
list(extract_documentation(data, "PYTHON3", "default")),
[DocumentationComment(" documentation in single line ",
"PYTHON3", "default",
"PYTHON3", "default", "",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(2, 1, 2, 38))])

Expand All @@ -234,6 +240,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",
"PYTHON3", "doxygen", "",
docstyle_PYTHON3_doxygen.markers[1],
TextRange.from_values(1, 1, 1, 55))])
2 changes: 1 addition & 1 deletion tests/bearlib/languages/documentation/documentation_extraction_testdata/data.cpp
View file
Expand Up @@ -23,7 +23,7 @@ int foobar(int xyz) {
void alternatestyle()
{}

/** ends instantly */
/** ends instantly */
void boofar()
{
return "foobar is happy";
Expand Down
7 changes: 6 additions & 1 deletion tests/bearlib/languages/documentation/documentation_extraction_testdata/data.py
View file
Expand Up @@ -9,7 +9,12 @@ def foobar_explosion(radius):
A nice and neat way of documenting code.
:param radius: The explosion radius.
"""
return 55 * radius
def get_55():
"""
A function that returns 55.
"""
return 55
return get_55() * radius

"""
Docstring with layouted text.
Expand Down

0 comments on commit 72b6c9c

Please sign in to comment.