def test_fields(self): c_doxygen = DocstyleDefinition.load('C', 'doxygen') uut = DocumentationComment('my doc', c_doxygen, ' ', ('/**', '*', '*/'), (25, 45)) self.assertEqual(uut.documentation, 'my doc') self.assertEqual(uut.language, 'c') 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, '\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) self.assertEqual(uut.metadata, python_doxygen_metadata)
def test_extract_documentation_CPP(self): data = DocumentationExtractionTest.load_testdata("data.cpp") # No built-in documentation for C++. with self.assertRaises(KeyError): tuple(extract_documentation(data, "CPP", "default")) docstyle_CPP_doxygen = DocstyleDefinition.load("CPP", "doxygen") self.assertEqual( tuple(extract_documentation(data, "CPP", "doxygen")), (DocumentationComment(("\n" " This is the main function.\n" " @returns Exit code.\n" " Or any other number.\n"), docstyle_CPP_doxygen.markers[0], TextRange.from_values(4, 1, 8, 4)), DocumentationComment( (" foobar\n" " @param xyz\n"), docstyle_CPP_doxygen.markers[0], TextRange.from_values(15, 1, 17, 4)), DocumentationComment(" Some alternate style of documentation\n", docstyle_CPP_doxygen.markers[4], TextRange.from_values(22, 1, 23, 1)), DocumentationComment(" ends instantly", docstyle_CPP_doxygen.markers[0], TextRange.from_values(26, 5, 26, 26)), DocumentationComment((" Should work\n" "\n" " even without a function standing below.\n" "\n" " @param foo WHAT PARAM PLEASE!?\n"), docstyle_CPP_doxygen.markers[4], TextRange.from_values(32, 1, 37, 1))))
def test_fields(self): c_doxygen = DocstyleDefinition.load("C", "doxygen") uut = DocumentationComment("my doc", c_doxygen, " ", ("/**", "*", "*/"), (25, 45)) self.assertEqual(uut.documentation, "my doc") self.assertEqual(uut.language, "c") 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, "\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) self.assertEqual(uut.metadata, python_doxygen_metadata)
def test_extract_documentation_CPP(self): data = load_testdata('data.cpp') # No built-in documentation for C++. with self.assertRaises(KeyError): tuple(extract_documentation(data, 'CPP', 'default')) docstyle_CPP_doxygen = DocstyleDefinition.load('CPP', 'doxygen') self.assertEqual( tuple(extract_documentation(data, 'CPP', 'doxygen')), (DocumentationComment( ('\n' ' This is the main function.\n' ' @returns Exit code.\n' ' Or any other number.\n'), docstyle_CPP_doxygen, '', docstyle_CPP_doxygen.markers[0], TextPosition(4, 1)), DocumentationComment( (' foobar\n' ' @param xyz\n'), docstyle_CPP_doxygen, '', docstyle_CPP_doxygen.markers[0], TextPosition(15, 1)), DocumentationComment(' Some alternate style of documentation\n', docstyle_CPP_doxygen, '', docstyle_CPP_doxygen.markers[4], TextPosition(22, 1)), DocumentationComment(' ends instantly', docstyle_CPP_doxygen, '\t', docstyle_CPP_doxygen.markers[0], TextPosition(26, 2)), DocumentationComment( (' Should work\n' '\n' ' even without a function standing below.\n' '\n' ' @param foo WHAT PARAM PLEASE!?\n'), docstyle_CPP_doxygen, '', docstyle_CPP_doxygen.markers[4], TextPosition(32, 1))))
def test_fields(self): uut = DocumentationComment("my doc", ("/**", "*", "*/"), (25, 45)) self.assertEqual(uut.documentation, "my doc") self.assertEqual(str(uut), "my doc") self.assertEqual(uut.marker, ("/**", "*", "*/")) self.assertEqual(uut.range, (25, 45)) uut = DocumentationComment("qwertzuiop", ("##", "#", "#"), None) self.assertEqual(uut.documentation, "qwertzuiop") self.assertEqual(str(uut), "qwertzuiop") self.assertEqual(uut.marker, ("##", "#", "#")) self.assertEqual(uut.range, None)
def test_not_implemented(self): raw_docstyle = DocstyleDefinition('nolang', 'nostyle', ('', '', ''), self.Metadata('', '', '', '', '')) not_implemented = DocumentationComment( 'some docs', raw_docstyle, None, None, None) with self.assertRaises(NotImplementedError): not_implemented.parse()
def _extract_doc_comment_from_line(content, line, column, regex, marker_dict, docstyle_definition): 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) if doc_comment is not None: end_line, end_column, documentation = doc_comment position = TextPosition(line + 1, len(indent) + 1) doc = DocumentationComment(documentation, docstyle_definition, indent, marker, position) break if doc_comment: return end_line, end_column, doc else: malformed_comment = MalformedComment( dedent("""\ Please check the docstring for faulty markers. A starting marker has been found, but no instance of DocComment is returned."""), line) return line + 1, 0, malformed_comment return line + 1, 0, None
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", "doxygen") expected = (DocumentationComment(("\n" "Module description.\n" "\n" "Some more foobar-like text.\n"), 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"), docstyle_PYTHON3_default.markers[0], TextRange.from_values(8, 5, 11, 8)), DocumentationComment( ("\n" "Docstring with layouted text.\n" "\n" " layouts inside docs are preserved for these " "documentation styles.\n" "this is intended.\n"), docstyle_PYTHON3_default.markers[0], TextRange.from_values(14, 1, 19, 4)), DocumentationComment( (" Docstring directly besides triple quotes.\n" " Continues here. "), docstyle_PYTHON3_default.markers[0], TextRange.from_values(21, 1, 22, 24)), DocumentationComment(("super\n" " nicely\n" "short"), docstyle_PYTHON3_default.markers[0], TextRange.from_values(35, 1, 37, 9))) self.assertEqual( tuple(extract_documentation(data, "PYTHON3", "default")), expected) # Change only the docstyle in expected results. expected = list( DocumentationComment(r.documentation, r.marker, r.range) for r in expected) expected.insert( 4, DocumentationComment( (" Alternate documentation style in doxygen.\n" " Subtext\n" " More subtext (not correctly aligned)\n" " sub-sub-text\n" "\n"), docstyle_PYTHON3_doxygen.markers[1], TextRange.from_values(25, 1, 30, 1))) self.assertEqual( list(extract_documentation(data, "PYTHON3", "doxygen")), expected)
def test_DocBaseClass_extraction_C(self): data = load_testdata('data.c') # No built-in documentation for C. with self.assertRaises(KeyError): tuple(DocBaseClass.extract(data, 'C', 'default')) docstyle_C_doxygen = DocstyleDefinition.load('C', 'doxygen') expected_results = (DocumentationComment( ('\n' ' This is the main function.\n' '\n' ' @returns Your favorite number.\n'), docstyle_C_doxygen, '', docstyle_C_doxygen.markers[0], TextPosition(3, 1)), DocumentationComment( ('\n' ' Preserves alignment\n' ' - Main item\n' ' - sub item\n' ' - sub sub item\n'), docstyle_C_doxygen, '', docstyle_C_doxygen.markers[2], TextPosition(15, 1)), DocumentationComment( (' ABC\n' ' Another type of comment\n' '\n' ' ...'), docstyle_C_doxygen, '', docstyle_C_doxygen.markers[1], TextPosition(23, 1)), DocumentationComment( (' foobar = barfoo.\n' ' @param x whatever...\n'), docstyle_C_doxygen, '', docstyle_C_doxygen.markers[0], TextPosition(28, 1))) self.assertEqual(tuple( DocBaseClass.extract(data, 'C', 'doxygen')), expected_results)
def test_extract_documentation_C(self): data = load_testdata("data.c") # No built-in documentation for C. with self.assertRaises(KeyError): tuple(extract_documentation(data, "C", "default")) docstyle_C_doxygen = DocstyleDefinition.load("C", "doxygen") expected_results = (DocumentationComment( ("\n" " This is the main function.\n" "\n" " @returns Your favorite number.\n"), docstyle_C_doxygen, "", docstyle_C_doxygen.markers[0], TextRange.from_values(3, 1, 7, 4)), DocumentationComment( ("\n" " Preserves alignment\n" " - Main item\n" " - sub item\n" " - sub sub item\n"), docstyle_C_doxygen, "", docstyle_C_doxygen.markers[2], TextRange.from_values(15, 1, 20, 4)), DocumentationComment( (" ABC\n" " Another type of comment\n" "\n" " ..."), docstyle_C_doxygen, "", docstyle_C_doxygen.markers[1], TextRange.from_values(23, 1, 26, 11)), DocumentationComment( (" foobar = barfoo.\n" " @param x whatever...\n"), docstyle_C_doxygen, "", docstyle_C_doxygen.markers[0], TextRange.from_values(28, 1, 30, 4))) self.assertEqual(tuple( extract_documentation(data, "C", "doxygen")), expected_results)
def test_extract_documentation_C_2(self): data = ['/** my main description\n', ' * continues here */'] docstyle_C_doxygen = DocstyleDefinition.load('C', 'doxygen') self.assertEqual(list(extract_documentation(data, 'C', 'doxygen')), [ DocumentationComment( ' my main description\n continues here', docstyle_C_doxygen, '', docstyle_C_doxygen.markers[0], TextPosition(1, 1)) ])
def test_extract_documentation_CPP_2(self): data = load_testdata('data2.cpp') docstyle_CPP_doxygen = DocstyleDefinition.load('CPP', 'doxygen') self.assertEqual(tuple(extract_documentation( data, 'CPP', 'doxygen')), (DocumentationComment( ('module comment\n' ' hello world\n'), docstyle_CPP_doxygen, '', docstyle_CPP_doxygen.markers[0], TextPosition(1, 1)), ))
def test_extract_documentation_CPP_2(self): data = DocumentationExtractionTest.load_testdata("data2.cpp") docstyle_CPP_doxygen = DocstyleDefinition.load("CPP", "doxygen") 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)), ))
def test_extract_documentation_C_2(self): data = ['/** my main description\n', ' * continues here */'] docstyle_C_doxygen = DocstyleDefinition.load("C", "doxygen") 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)) ])
def check_docstring(self, docstring, expected=[]): self.assertIsInstance(docstring, str, "expected needs to be a string for this test.") self.assertIsInstance(expected, list, "expected needs to be a list for this test.") doc_comment = DocumentationComment(docstring, "python", "default", None, None, None) parsed_metadata = doc_comment.parse() self.assertEqual(parsed_metadata, expected)
def test_extract_documentation_PYTHON3_2(self): data = ['\n', '""" documentation in single line """\n', 'print(1)\n'] docstyle_PYTHON3_default = DocstyleDefinition.load("PYTHON3", "default") self.assertEqual( list(extract_documentation(data, "PYTHON3", "default")), [DocumentationComment(" documentation in single line ", docstyle_PYTHON3_default.markers[0], TextRange.from_values(2, 1, 2, 38))])
def test_DocBaseClass_extraction_PYTHON3_2(self): data = ['\n', '""" documentation in single line """\n', 'print(1)\n'] docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3', 'default') self.assertEqual( list(DocBaseClass.extract(data, 'PYTHON3', 'default')), [DocumentationComment(' documentation in single line ', docstyle_PYTHON3_default, '', docstyle_PYTHON3_default.markers[0], TextPosition(2, 1))])
def test_DocBaseClass_extraction_PYTHON3_5(self): data = ['r"""\n', 'This is a raw docstring\n', '"""\n'] docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3', 'default') self.assertEqual( list(DocBaseClass.extract(data, 'PYTHON3', 'default')), [DocumentationComment('\nThis is a raw docstring\n', docstyle_PYTHON3_default, 'r', docstyle_PYTHON3_default.markers[0], TextPosition(1, 2))])
def test_extract_documentation_PYTHON3_3(self): data = ['## documentation in single line without return at end.'] docstyle_PYTHON3_doxygen = DocstyleDefinition.load("PYTHON3", "doxygen") self.assertEqual( list(extract_documentation(data, "PYTHON3", "doxygen")), [DocumentationComment(" documentation in single line without " "return at end.", docstyle_PYTHON3_doxygen.markers[1], TextRange.from_values(1, 1, 1, 55))])
def test_extract_documentation_PYTHON3_3(self): data = ['## documentation in single line without return at end.'] docstyle_PYTHON3_doxygen = DocstyleDefinition.load( 'PYTHON3', 'doxygen') self.assertEqual( list(extract_documentation(data, 'PYTHON3', 'doxygen')), [ DocumentationComment( ' documentation in single line without ' 'return at end.', docstyle_PYTHON3_doxygen, '', docstyle_PYTHON3_doxygen.markers[1], TextPosition(1, 1)) ])
def check_docstring(self, docstring, expected=[]): self.assertIsInstance(docstring, str, 'expected needs to be a string for this test.') self.assertIsInstance(expected, list, 'expected needs to be a list for this test.') 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)
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)
def _extract_doc_comment_from_line(content, line, column, regex, marker_dict): begin_match = regex.search(content[line], column) if begin_match: column = begin_match.end() for marker in marker_dict[begin_match.group()]: doc_comment = _extract_doc_comment(content, line, column, marker) if doc_comment is not None: end_line, end_column, documentation = doc_comment rng = TextRange.from_values(line + 1, begin_match.start() + 1, end_line + 1, end_column + 1) doc = DocumentationComment(documentation, marker, rng) return end_line, end_column, doc return line + 1, 0, None
def _extract_doc_comment_from_line(content, line, column, regex, marker_dict, docstyle_definition): cur_line = content[line] begin_match = regex.search(cur_line, column) if begin_match: column = begin_match.end() indent = begin_match.group('indent') for marker in marker_dict[begin_match.group('marker')]: doc_comment = _extract_doc_comment(content, line, column, marker) if doc_comment is not None: end_line, end_column, documentation = doc_comment position = TextPosition(line + 1, len(indent) + 1) doc = DocumentationComment(documentation, docstyle_definition, indent, marker, position) return end_line, end_column, doc return line + 1, 0, None
def test_not_implemented(self): not_implemented = DocumentationComment("some docs", "nolang", "doxygen", None, None, None) with self.assertRaises(NotImplementedError): not_implemented.parse()
def test_extract_documentation_PYTHON3(self): data = load_testdata('data.py') docstyle_PYTHON3_default = DocstyleDefinition.load( 'PYTHON3', 'default') docstyle_PYTHON3_doxygen = DocstyleDefinition.load( 'PYTHON3', 'doxygen') expected = ( DocumentationComment(('\n' 'Module description.\n' '\n' 'Some more foobar-like text.\n'), docstyle_PYTHON3_default, '', docstyle_PYTHON3_default.markers[0], TextPosition(1, 1)), DocumentationComment(('\n' 'A nice and neat way of documenting code.\n' ':param radius: The explosion radius.\n'), docstyle_PYTHON3_default, ' ' * 4, docstyle_PYTHON3_default.markers[0], TextPosition(8, 5)), DocumentationComment('\nA function that returns 55.\n', docstyle_PYTHON3_default, ' ' * 8, docstyle_PYTHON3_default.markers[0], TextPosition(13, 9)), DocumentationComment( ('\n' 'Docstring with layouted text.\n' '\n' ' layouts inside docs are preserved for these ' 'documentation styles.\n' 'this is intended.\n'), docstyle_PYTHON3_default, '', docstyle_PYTHON3_default.markers[0], TextPosition(19, 1)), DocumentationComment( (' Docstring directly besides triple quotes.\n' ' Continues here. '), docstyle_PYTHON3_default, '', docstyle_PYTHON3_default.markers[0], TextPosition(26, 1)), DocumentationComment(('super\n' ' nicely\n' 'short'), docstyle_PYTHON3_default, '', docstyle_PYTHON3_default.markers[0], TextPosition(40, 1)), DocumentationComment(('\n' 'A bad indented docstring\n' ' Improper indentation.\n' ':param impact: The force of Impact.\n'), docstyle_PYTHON3_default, ' ' * 4, docstyle_PYTHON3_default.markers[0], TextPosition(45, 5)), ) self.assertEqual( tuple(extract_documentation(data, 'PYTHON3', 'default')), expected) # Change only the docstyle in expected results. expected = list( DocumentationComment(r.documentation, docstyle_PYTHON3_doxygen, r.indent, r.marker, r.position) for r in expected) expected.insert( 5, DocumentationComment( (' Alternate documentation style in doxygen.\n' ' Subtext\n' ' More subtext (not correctly aligned)\n' ' sub-sub-text\n' '\n'), docstyle_PYTHON3_doxygen, '', docstyle_PYTHON3_doxygen.markers[1], TextPosition(30, 1))) self.assertEqual( list(extract_documentation(data, 'PYTHON3', 'doxygen')), expected)