From 3a78aa9975d9649a1f62c3ac623f9617695b0582 Mon Sep 17 00:00:00 2001 From: SanketDG Date: Tue, 12 Jul 2016 19:35:50 +0530 Subject: [PATCH] DocumentationComment: Use DocstyleDefinition A docstyle_definition is now used to store the language, docstyle and the symbols. --- .../documentation/DocumentationComment.py | 19 ++++++-- .../documentation/DocumentationExtraction.py | 28 ++++++------ .../documentation/DocumentationCommentTest.py | 26 ++++++++--- .../DocumentationExtractionTest.py | 43 +++++++++---------- 4 files changed, 69 insertions(+), 47 deletions(-) diff --git a/coalib/bearlib/languages/documentation/DocumentationComment.py b/coalib/bearlib/languages/documentation/DocumentationComment.py index 7407bb356c..4af279801f 100644 --- a/coalib/bearlib/languages/documentation/DocumentationComment.py +++ b/coalib/bearlib/languages/documentation/DocumentationComment.py @@ -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. @@ -30,8 +30,7 @@ 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 @@ -39,6 +38,18 @@ def __init__(self, documentation, language, 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. diff --git a/coalib/bearlib/languages/documentation/DocumentationExtraction.py b/coalib/bearlib/languages/documentation/DocumentationExtraction.py index a5e8f8e847..6b3181fde2 100644 --- a/coalib/bearlib/languages/documentation/DocumentationExtraction.py +++ b/coalib/bearlib/languages/documentation/DocumentationExtraction.py @@ -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: @@ -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. @@ -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: @@ -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 @@ -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) diff --git a/tests/bearlib/languages/documentation/DocumentationCommentTest.py b/tests/bearlib/languages/documentation/DocumentationCommentTest.py index bb1f5a369a..3dff57adbc 100644 --- a/tests/bearlib/languages/documentation/DocumentationCommentTest.py +++ b/tests/bearlib/languages/documentation/DocumentationCommentTest.py @@ -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 ( @@ -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) @@ -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() @@ -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) diff --git a/tests/bearlib/languages/documentation/DocumentationExtractionTest.py b/tests/bearlib/languages/documentation/DocumentationExtractionTest.py index 3028fabd1b..61be5601f8 100644 --- a/tests/bearlib/languages/documentation/DocumentationExtractionTest.py +++ b/tests/bearlib/languages/documentation/DocumentationExtractionTest.py @@ -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( @@ -40,7 +40,7 @@ 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( @@ -48,13 +48,13 @@ def test_extract_documentation_C(self): " 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))) @@ -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))]) @@ -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( @@ -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)))) @@ -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)),)) @@ -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( @@ -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))) @@ -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) @@ -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))) @@ -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))]) @@ -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))])