From 56e180254ad37c33593e851a7e4bcb406964ab81 Mon Sep 17 00:00:00 2001 From: SanketDG Date: Tue, 17 May 2016 11:54:32 +0530 Subject: [PATCH] DocumentationComment: Add language, docstyle param The docstyle and language is needed for language independent documentation extraction. --- .../documentation/DocumentationComment.py | 12 ++++--- .../documentation/DocumentationExtraction.py | 15 +++++--- .../documentation/DocumentationCommentTest.py | 8 +++++ .../DocumentationExtractionTest.py | 35 +++++++++++++++---- 4 files changed, 54 insertions(+), 16 deletions(-) diff --git a/coalib/bearlib/languages/documentation/DocumentationComment.py b/coalib/bearlib/languages/documentation/DocumentationComment.py index 255e973c77..4f66d203a4 100644 --- a/coalib/bearlib/languages/documentation/DocumentationComment.py +++ b/coalib/bearlib/languages/documentation/DocumentationComment.py @@ -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 diff --git a/coalib/bearlib/languages/documentation/DocumentationExtraction.py b/coalib/bearlib/languages/documentation/DocumentationExtraction.py index 6a83108cda..d9a408e69a 100644 --- a/coalib/bearlib/languages/documentation/DocumentationExtraction.py +++ b/coalib/bearlib/languages/documentation/DocumentationExtraction.py @@ -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) diff --git a/tests/bearlib/languages/documentation/DocumentationCommentTest.py b/tests/bearlib/languages/documentation/DocumentationCommentTest.py index 860bdd92fc..f1d6c72f68 100644 --- a/tests/bearlib/languages/documentation/DocumentationCommentTest.py +++ b/tests/bearlib/languages/documentation/DocumentationCommentTest.py @@ -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) diff --git a/tests/bearlib/languages/documentation/DocumentationExtractionTest.py b/tests/bearlib/languages/documentation/DocumentationExtractionTest.py index 21752f552b..29bf7a4852 100644 --- a/tests/bearlib/languages/documentation/DocumentationExtractionTest.py +++ b/tests/bearlib/languages/documentation/DocumentationExtractionTest.py @@ -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,6 +48,7 @@ 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( @@ -54,16 +56,19 @@ def test_extract_documentation_C(self): " 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))])