Skip to content

Commit

Permalink
DocumentationComment: Use DocstyleDefinition
Browse files Browse the repository at this point in the history 
A docstyle_definition is now used to store the language, docstyle
and the symbols.
  • Loading branch information
@SanketDG
SanketDG committed Aug 14, 2016
1 parent edc67aa commit 3a78aa9
Show file tree
Hide file tree
Showing 4 changed files with 69 additions and 47 deletions.
19 changes: 15 additions & 4 deletions coalib/bearlib/languages/documentation/DocumentationComment.py
View file
Expand Up @@ -15,8 +15,8 @@ class DocumentationComment:
ReturnValue = namedtuple('ReturnValue', 'desc')
Description = namedtuple('Description', 'desc')

def __init__(self, documentation, language,
docstyle, indent, marker, range):
def __init__(self, documentation, docstyle_definition,
indent, marker, range):
"""
Instantiates a new DocumentationComment.
Expand All @@ -30,15 +30,26 @@ def __init__(self, documentation, language,
:param range: The position range of type TextRange.
"""
self.documentation = documentation
self.language = language.lower()
self.docstyle = docstyle.lower()
self.docstyle_definition = docstyle_definition
self.indent = indent
self.marker = marker
self.range = range

def __str__(self):
return self.documentation

@property
def language(self):
return self.docstyle_definition.language

@property
def docstyle(self):
return self.docstyle_definition.docstyle

@property
def metadata(self):
return self.docstyle_definition.metadata

def parse(self):
"""
Parses documentation independent of language and docstyle.
Expand Down
28 changes: 14 additions & 14 deletions coalib/bearlib/languages/documentation/DocumentationExtraction.py
View file
Expand Up @@ -184,7 +184,7 @@ def _compile_multi_match_regex(strings):


def _extract_doc_comment_from_line(content, line, column, regex,
marker_dict, language, docstyle):
marker_dict, docstyle_definition):
cur_line = content[line]
begin_match = regex.search(cur_line, column)
if begin_match:
Expand All @@ -199,15 +199,15 @@ def _extract_doc_comment_from_line(content, line, column, regex,
begin_match.start() + 1,
end_line + 1,
end_column + 1)
doc = DocumentationComment(documentation, language,
docstyle, indent, marker, rng)
doc = DocumentationComment(documentation, docstyle_definition,
indent, marker, rng)

return end_line, end_column, doc

return line + 1, 0, None


def extract_documentation_with_markers(content, markers, language, docstyle):
def extract_documentation_with_markers(content, docstyle_definition):
"""
Extracts all documentation texts inside the given source-code-string.
Expand All @@ -225,6 +225,8 @@ def extract_documentation_with_markers(content, markers, language, docstyle):
# begin sequence we initially want to search for in source code. Then
# the possible found documentation match is processed further with the
# rest markers.
markers = docstyle_definition.markers

marker_dict = {}
for marker_set in markers:
if marker_set[0] not in marker_dict:
Expand All @@ -240,13 +242,13 @@ def extract_documentation_with_markers(content, markers, language, docstyle):
line = 0
column = 0
while line < len(content):
line, column, doc = _extract_doc_comment_from_line(content,
line,
column,
begin_regex,
marker_dict,
language,
docstyle)
line, column, doc = _extract_doc_comment_from_line(
content,
line,
column,
begin_regex,
marker_dict,
docstyle_definition)
if doc:
yield doc

Expand Down Expand Up @@ -278,6 +280,4 @@ def extract_documentation(content, language, docstyle):
found in the content.
"""
docstyle_definition = DocstyleDefinition.load(language, docstyle)
return extract_documentation_with_markers(content,
docstyle_definition.markers,
language, docstyle)
return extract_documentation_with_markers(content, docstyle_definition)
26 changes: 19 additions & 7 deletions tests/bearlib/languages/documentation/DocumentationCommentTest.py
View file
@@ -1,5 +1,7 @@
import unittest

from coalib.bearlib.languages.documentation.DocstyleDefinition import (
DocstyleDefinition)
from coalib.bearlib.languages.documentation.DocumentationComment import (
DocumentationComment)
from coalib.bearlib.languages.documentation.DocumentationExtraction import (
Expand All @@ -14,28 +16,33 @@ class DocumentationCommentTest(unittest.TestCase):
Parameter = DocumentationComment.Parameter
ReturnValue = DocumentationComment.ReturnValue

Metadata = DocstyleDefinition.Metadata


class GeneralDocumentationCommentTest(DocumentationCommentTest):

def test_fields(self):
c_doxygen = DocstyleDefinition.load("C", "doxygen")
uut = DocumentationComment("my doc",
"c",
"default",
c_doxygen,
" ",
("/**", "*", "*/"),
(25, 45))

self.assertEqual(uut.documentation, "my doc")
self.assertEqual(uut.language, "c")
self.assertEqual(uut.docstyle, "default")
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))

python_doxygen = DocstyleDefinition.load("python", "doxygen")

python_doxygen_metadata = self.Metadata("@param ", " ", "@return ")

uut = DocumentationComment("qwertzuiop",
"python",
"doxygen",
python_doxygen,
"\t",
("##", "#", "#"),
None)
Expand All @@ -47,10 +54,13 @@ def test_fields(self):
self.assertEqual(str(uut), "qwertzuiop")
self.assertEqual(uut.marker, ("##", "#", "#"))
self.assertEqual(uut.range, None)
self.assertEqual(uut.metadata, python_doxygen_metadata)

def test_not_implemented(self):
raw_docstyle = DocstyleDefinition("nolang", "nostyle", ('', '', ''),
self.Metadata('', '', ''))
not_implemented = DocumentationComment(
"some docs", "nolang", "doxygen", None, None, None)
"some docs", raw_docstyle, None, None, None)
with self.assertRaises(NotImplementedError):
not_implemented.parse()

Expand All @@ -66,7 +76,9 @@ def check_docstring(self, docstring, expected=[]):
list,
"expected needs to be a list for this test.")

doc_comment = DocumentationComment(docstring, "python", "default",
python_default = DocstyleDefinition.load("python", "default")

doc_comment = DocumentationComment(docstring, python_default,
None, None, None)
parsed_metadata = doc_comment.parse()
self.assertEqual(parsed_metadata, expected)
Expand Down
43 changes: 21 additions & 22 deletions tests/bearlib/languages/documentation/DocumentationExtractionTest.py
View file
Expand Up @@ -31,7 +31,7 @@ def test_extract_documentation_C(self):
" This is the main function.\n"
"\n"
" @returns Your favorite number.\n"),
"C", "doxygen", "",
docstyle_C_doxygen, "",
docstyle_C_doxygen.markers[0],
TextRange.from_values(3, 1, 7, 4)),
DocumentationComment(
Expand All @@ -40,21 +40,21 @@ def test_extract_documentation_C(self):
" - Main item\n"
" - sub item\n"
" - sub sub item\n"),
"C", "doxygen", "",
docstyle_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, "",
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, "",
docstyle_C_doxygen.markers[0],
TextRange.from_values(28, 1, 30, 4)))

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

Expand All @@ -89,23 +89,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, "",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(4, 1, 8, 4)),
DocumentationComment(
(" foobar\n"
" @param xyz\n"),
"CPP", "doxygen", "",
docstyle_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, "",
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(22, 1, 23, 1)),
DocumentationComment(
" ends instantly",
"CPP", "doxygen", "\t",
docstyle_CPP_doxygen, "\t",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(26, 2, 26, 23)),
DocumentationComment(
Expand All @@ -114,7 +114,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, "",
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(32, 1, 37, 1))))

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

Expand All @@ -143,19 +143,19 @@ def test_extract_documentation_PYTHON3(self):
"Module description.\n"
"\n"
"Some more foobar-like text.\n"),
"PYTHON3", "default", "",
docstyle_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", " " * 4,
docstyle_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, " " * 8,
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(13, 9, 15, 12)),
DocumentationComment(
Expand All @@ -165,20 +165,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, "",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(19, 1, 24, 4)),
DocumentationComment(
(" Docstring directly besides triple quotes.\n"
" Continues here. "),
"PYTHON3", "default", "",
docstyle_PYTHON3_default, "",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(26, 1, 27, 24)),
DocumentationComment(
("super\n"
" nicely\n"
"short"),
"PYTHON3", "default", "",
docstyle_PYTHON3_default, "",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(40, 1, 42, 9)))

Expand All @@ -188,8 +188,7 @@ def test_extract_documentation_PYTHON3(self):

# Change only the docstyle in expected results.
expected = list(DocumentationComment(r.documentation,
r.language,
"doxygen",
docstyle_PYTHON3_doxygen,
r.indent,
r.marker,
r.range)
Expand All @@ -201,7 +200,7 @@ def test_extract_documentation_PYTHON3(self):
" More subtext (not correctly aligned)\n"
" sub-sub-text\n"
"\n"),
"PYTHON3", "doxygen", "",
docstyle_PYTHON3_doxygen, "",
docstyle_PYTHON3_doxygen.markers[1],
TextRange.from_values(30, 1, 35, 1)))

Expand All @@ -218,7 +217,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, "",
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(2, 1, 2, 38))])

Expand All @@ -232,6 +231,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, "",
docstyle_PYTHON3_doxygen.markers[1],
TextRange.from_values(1, 1, 1, 55))])

0 comments on commit 3a78aa9

Please sign in to comment.