def test_fail_instantiation(self): with self.assertRaises(ValueError): DocstyleDefinition('PYTHON', 'doxyGEN', (('##', '#'), ), self.dummy_metadata, self.dummy_class_padding, self.dummy_function_padding, self.dummy_docstring_type_regex, self.dummy_docstring_position) with self.assertRaises(ValueError): DocstyleDefinition('WEIRD-PY', 'schloxygen', (('##+', 'x', 'y', 'z'), ), self.dummy_metadata, self.dummy_class_padding, self.dummy_function_padding, self.dummy_docstring_type_regex, self.dummy_docstring_position) with self.assertRaises(ValueError): DocstyleDefinition('PYTHON', 'doxygen', (('##', '', '#'), ('"""', '"""')), self.dummy_metadata, self.dummy_class_padding, self.dummy_function_padding, self.dummy_docstring_type_regex, self.dummy_docstring_position) with self.assertRaises(TypeError): DocstyleDefinition(123, ['doxygen'], (('"""', '"""')), self.dummy_metadata, self.dummy_class_padding, self.dummy_function_padding, self.dummy_docstring_type_regex, self.dummy_docstring_position) with self.assertRaises(TypeError): DocstyleDefinition('language', ['doxygen'], (('"""', '"""')), 'metdata', 'clpading', 'dfpadding', 'kind')
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_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_properties(self): uut = DocstyleDefinition("C", "doxygen", (("/**", "*", "*/"),), self.dummy_metadata) self.assertEqual(uut.language, "c") self.assertEqual(uut.docstyle, "doxygen") self.assertEqual(uut.markers, (("/**", "*", "*/"),)) self.assertEqual(uut.metadata, self.dummy_metadata) uut = DocstyleDefinition("PYTHON", "doxyGEN", [("##", "", "#")], self.dummy_metadata) self.assertEqual(uut.language, "python") self.assertEqual(uut.docstyle, "doxygen") self.assertEqual(uut.markers, (("##", "", "#"),)) self.assertEqual(uut.metadata, self.dummy_metadata) uut = DocstyleDefinition("I2C", "my-custom-tool", (["~~", "/~", "/~"], (">!", ">>", ">>")), self.dummy_metadata) self.assertEqual(uut.language, "i2c") self.assertEqual(uut.docstyle, "my-custom-tool") self.assertEqual(uut.markers, (("~~", "/~", "/~"), (">!", ">>", ">>"))) self.assertEqual(uut.metadata, self.dummy_metadata) uut = DocstyleDefinition("Cpp", "doxygen", ("~~", "/~", "/~"), self.dummy_metadata) self.assertEqual(uut.language, "cpp") self.assertEqual(uut.docstyle, "doxygen") self.assertEqual(uut.markers, (("~~", "/~", "/~"),)) self.assertEqual(uut.metadata, self.dummy_metadata)
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_properties(self): uut = DocstyleDefinition('C', 'doxygen', (('/**', '*', '*/'), ), self.dummy_metadata) self.assertEqual(uut.language, 'c') self.assertEqual(uut.docstyle, 'doxygen') self.assertEqual(uut.markers, (('/**', '*', '*/'), )) self.assertEqual(uut.metadata, self.dummy_metadata) uut = DocstyleDefinition('PYTHON', 'doxyGEN', [('##', '', '#')], self.dummy_metadata) self.assertEqual(uut.language, 'python') self.assertEqual(uut.docstyle, 'doxygen') self.assertEqual(uut.markers, (('##', '', '#'), )) self.assertEqual(uut.metadata, self.dummy_metadata) uut = DocstyleDefinition('I2C', 'my-custom-tool', (['~~', '/~', '/~'], ('>!', '>>', '>>')), self.dummy_metadata) self.assertEqual(uut.language, 'i2c') self.assertEqual(uut.docstyle, 'my-custom-tool') self.assertEqual(uut.markers, (('~~', '/~', '/~'), ('>!', '>>', '>>'))) self.assertEqual(uut.metadata, self.dummy_metadata) uut = DocstyleDefinition('Cpp', 'doxygen', ('~~', '/~', '/~'), self.dummy_metadata) self.assertEqual(uut.language, 'cpp') self.assertEqual(uut.docstyle, 'doxygen') self.assertEqual(uut.markers, (('~~', '/~', '/~'), )) self.assertEqual(uut.metadata, self.dummy_metadata)
def test_fail_instantation(self): with self.assertRaises(ValueError): DocstyleDefinition("PYTHON", "doxyGEN", (("##", "#"), )) with self.assertRaises(ValueError): DocstyleDefinition("WEIRD-PY", "schloxygen", (("##+", "x", "y", "z"), )) with self.assertRaises(ValueError): DocstyleDefinition("PYTHON", "doxygen", (("##", "", "#"), ('"""', '"""')))
def test_load(self): # Test unregistered docstyle. with self.assertRaises(FileNotFoundError): next(DocstyleDefinition.load("PYTHON", "INVALID")) # Test unregistered language in existing docstyle. with self.assertRaises(KeyError): next(DocstyleDefinition.load("bake-a-cake", "default")) # Test python 3 default configuration and if everything is parsed # right. result = DocstyleDefinition.load("PYTHON3", "default") self.assertEqual(result.language, "python3") self.assertEqual(result.docstyle, "default") self.assertEqual(result.markers, (('"""', '', '"""'),))
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 test_load(self): # Test unregistered docstyle. with self.assertRaises(FileNotFoundError): next(DocstyleDefinition.load("PYTHON", "INVALID")) # Test unregistered language in existing docstyle. with self.assertRaises(KeyError): next(DocstyleDefinition.load("bake-a-cake", "default")) # Test python 3 default configuration and if everything is parsed # right. result = DocstyleDefinition.load("PYTHON3", "default") self.assertEqual(result.language, "python3") self.assertEqual(result.docstyle, "default") self.assertEqual(result.markers, (('"""', '', '"""'), ))
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_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 extract_documentation(content, language, docstyle): """ Extracts all documentation texts inside the given source-code-string using the coala docstyle definition files. The documentation texts are sorted by their order appearing in ``content``. For more information about how documentation comments are identified and extracted, see DocstyleDefinition.doctypes enumeration. :param content: The source-code-string where to extract documentation from. Needs to be a list or tuple where each string item is a single line (including ending whitespaces like ``\\n``). :param language: The programming language used. :param docstyle: The documentation style/tool used (e.g. doxygen). :raises FileNotFoundError: Raised when the docstyle definition file was not found. :raises KeyError: Raised when the given language is not defined in given docstyle. :raises ValueError: Raised when a docstyle definition setting has an invalid format. :return: An iterator returning each DocumentationComment found in the content. """ docstyle_definition = DocstyleDefinition.load(language, docstyle) return extract_documentation_with_markers(content, docstyle_definition.markers)
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', 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_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 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.markers[0], TextRange.from_values(1, 1, 2, 21))])
def test_DocBaseClass_instantiate_docstring_type_PYTHON3_14(self): data = [ '## Documentation for a class.\n', '#\n', '# More details.\n', 'class PyClass:\n', '\n' ] docstyle_PYTHON3_doxygen = DocstyleDefinition.load( 'PYTHON3', 'doxygen') for doc in DocBaseClass.extract(data, 'PYTHON3', 'doxygen'): self.assertEqual(doc.docstring_type, 'class')
def test_DocBaseClass_instantiate_docstring_type_PYTHON3_15(self): data = [ 'def some_function():\n', '"""\n', 'documentation\n', '"""\n', 'class myPrivateClass:\n', ' pass' ] docstyle_PYTHON3_default = DocstyleDefinition.load( 'PYTHON3', 'default') for doc in DocBaseClass.extract(data, 'PYTHON3', 'default'): self.assertEqual(doc.docstring_type, 'function')
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_instantiate_docstring_type_PYTHON3_11(self): data = [ 'def xyz:\n', ' """\n', ' This docstring is of docstring_type function\n', ' """\n' ] docstyle_PYTHON3_default = DocstyleDefinition.load( 'PYTHON3', 'default') for doc in DocBaseClass.extract(data, 'PYTHON3', 'default'): self.assertEqual(doc.docstring_type, 'function')
def test_DocBaseClass_extraction_C_2(self): data = ['/** my main description\n', ' * continues here */'] docstyle_C_doxygen = DocstyleDefinition.load('C', 'doxygen') self.assertEqual( list(DocBaseClass.extract(data, 'C', 'doxygen')), [DocumentationComment(' my main description\n continues here', docstyle_C_doxygen, '', docstyle_C_doxygen.markers[0], TextPosition(1, 1))])
def test_load_external_coalang(self): with TemporaryDirectory() as directory: coalang_file = os.path.join(directory, "custom.coalang") with open(coalang_file, "w") as file: file.write("[COOL]\ndoc-markers = @@,@@,@@\n") result = DocstyleDefinition.load( "cool", "custom", coalang_dir=directory) self.assertEqual(result.language, "cool") self.assertEqual(result.docstyle, "custom") self.assertEqual(result.markers, (('@@', '@@', '@@'),))
def test_get_available_definitions_on_wrong_files(self, confparser_mock, iglob_mock): # Test the case when a coalang was provided with uppercase letters. confparser_instance_mock = confparser_mock.return_value confparser_instance_mock.parse.return_value = ['X'] iglob_mock.return_value = [ 'some/CUSTOMSTYLE.coalang', 'SOME/xlang.coalang' ] self.assertEqual(list(DocstyleDefinition.get_available_definitions()), [('xlang', 'x')])
def test_get_available_definitions_on_wrong_files(self, confparser_mock, iglob_mock): # Test the case when a coalang was provided with uppercase letters. confparser_instance_mock = confparser_mock.return_value confparser_instance_mock.parse.return_value = ["X"] iglob_mock.return_value = ['some/CUSTOMSTYLE.coalang', 'SOME/xlang.coalang'] self.assertEqual(list(DocstyleDefinition.get_available_definitions()), [('xlang', 'x')])
def test_DocBaseClass_instantiate_docstring_type_PYTHON3_11(self): data = ['def xyz:\n', ' """\n', ' This docstring is of docstring_type function\n', ' """\n'] docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3', 'default') for doc in DocBaseClass.extract(data, 'PYTHON3', 'default'): self.assertEqual(doc.docstring_type, 'function')
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_DocBaseClass_instantiate_padding_PYTHON3_6(self): data = [ 'def some_function:\n', '\n', ' """ documentation in single line """\n', '\n', '\n', 'print(1)' ] docstyle_PYTHON3_default = DocstyleDefinition.load( 'PYTHON3', 'default') for doc in DocBaseClass.extract(data, 'PYTHON3', 'default'): self.assertEqual([doc.top_padding, doc.bottom_padding], [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_DocBaseClass_instantiate_docstring_type_PYTHON3_14(self): data = ['## Documentation for a class.\n', '#\n', '# More details.\n', 'class PyClass:\n', '\n'] docstyle_PYTHON3_doxygen = DocstyleDefinition.load('PYTHON3', 'doxygen') for doc in DocBaseClass.extract(data, 'PYTHON3', 'doxygen'): self.assertEqual(doc.docstring_type, 'class')
def test_DocBaseClass_instantiate_padding_inline_PYTHON3_9(self): # Paddings will not be instantiated for docstring_type=others data = [ '\n', ' """\n', ' documentation in single line\n', ' """ # This is inline docstring', '\n', '\n', 'print(1)' ] docstyle_PYTHON3_default = DocstyleDefinition.load( 'PYTHON3', 'default') for doc in DocBaseClass.extract(data, 'PYTHON3', 'default'): self.assertEqual([doc.top_padding, doc.bottom_padding], [0, 0])
def test_DocBaseClass_instantiate_docstring_type_PYTHON3_12(self): data = [ '\n', ' """\n', ' This docstring is of docstring_type others\n', ' """\n', '\n', 'print(1)' ] docstyle_PYTHON3_default = DocstyleDefinition.load( 'PYTHON3', 'default') for doc in DocBaseClass.extract(data, 'PYTHON3', 'default'): self.assertEqual(doc.docstring_type, 'others')
def test_fail_instantation(self): with self.assertRaises(ValueError): DocstyleDefinition('PYTHON', 'doxyGEN', (('##', '#'), ), self.dummy_metadata) with self.assertRaises(ValueError): DocstyleDefinition('WEIRD-PY', 'schloxygen', (('##+', 'x', 'y', 'z'), ), self.dummy_metadata) with self.assertRaises(ValueError): DocstyleDefinition('PYTHON', 'doxygen', (('##', '', '#'), ('"""', '"""')), self.dummy_metadata) with self.assertRaises(TypeError): DocstyleDefinition(123, ['doxygen'], (('"""', '"""')), self.dummy_metadata) with self.assertRaises(TypeError): DocstyleDefinition('language', ['doxygen'], (('"""', '"""')), 'metdata')
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_CPP_2(self): data = load_testdata('data2.cpp') docstyle_CPP_doxygen = DocstyleDefinition.load('CPP', 'doxygen') self.assertEqual(tuple(DocBaseClass.extract(data, 'CPP', 'doxygen')), (DocumentationComment( ('module comment\n' ' hello world\n'), docstyle_CPP_doxygen, '', docstyle_CPP_doxygen.markers[0], TextPosition(1, 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_DocBaseClass_extraction_PYTHON3_4(self): data = ['\n', 'triple_quote_string_test = """\n', 'This is not a docstring\n', '"""\n'] docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3', 'default') # Nothing is yielded as triple quote string literals are being # ignored. self.assertEqual( list(DocBaseClass.extract(data, 'PYTHON3', 'default')), [])
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], TextRange.from_values(1, 1, 3, 4)),))
def test_load(self): # Test unregistered docstyle. with self.assertRaises(FileNotFoundError): next(DocstyleDefinition.load('PYTHON', 'INVALID')) # Test unregistered language in existing docstyle. with self.assertRaises(KeyError): next(DocstyleDefinition.load('bake-a-cake', 'default')) # Test wrong argument type. with self.assertRaises(TypeError): next(DocstyleDefinition.load(123, ['list'])) # Test python 3 default configuration and if everything is parsed # right. result = DocstyleDefinition.load('PYTHON3', 'default') self.assertEqual(result.language, 'python3') self.assertEqual(result.docstyle, 'default') self.assertEqual(result.markers, (('"""', '', '"""'),)) self.assertEqual(result.metadata, self.dummy_metadata)
def test_DocBaseClass_extraction_PYTHON3_3(self): data = ['## documentation in single line without return at end.'] docstyle_PYTHON3_doxygen = DocstyleDefinition.load('PYTHON3', 'doxygen') self.assertEqual( list(DocBaseClass.extract(data, 'PYTHON3', 'doxygen')), [DocumentationComment(' documentation in single line without ' 'return at end.', docstyle_PYTHON3_doxygen, '', docstyle_PYTHON3_doxygen.markers[1], TextPosition(1, 1))])
def test_DocBaseClass_instantiate_docstring_type_PYTHON3_12(self): data = ['\n', ' """\n', ' This docstring is of docstring_type others\n', ' """\n', '\n', 'print(1)'] docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3', 'default') for doc in DocBaseClass.extract(data, 'PYTHON3', 'default'): self.assertEqual(doc.docstring_type, 'others')
def test_DocBaseClass_instantiate_docstring_type_PYTHON3_15(self): data = ['def some_function():\n', '"""\n', 'documentation\n', '"""\n', 'class myPrivateClass:\n', ' pass'] docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3', 'default') for doc in DocBaseClass.extract(data, 'PYTHON3', 'default'): self.assertEqual(doc.docstring_type, 'function')
def test_DocBaseClass_instantiate_padding_PYTHON3_6(self): data = ['def some_function:\n', '\n', ' """ documentation in single line """\n', '\n', '\n', 'print(1)'] docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3', 'default') for doc in DocBaseClass.extract(data, 'PYTHON3', 'default'): self.assertEqual([doc.top_padding, doc.bottom_padding], [1, 2])
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_from_metadata(self): data = load_testdata("default.py") original = list(extract_documentation(data, "python", "default")) parsed_docs = [(doc.parse(), doc.marker, doc.indent, doc.range) for doc in original] docstyle_definition = DocstyleDefinition.load("python", "default") assembled_docs = [DocumentationComment.from_metadata( doc[0], docstyle_definition, doc[1], doc[2], doc[3]) for doc in parsed_docs] self.assertEqual(assembled_docs, original)
def test_from_metadata(self): data = load_testdata('default.py') original = list(DocBaseClass.extract(data, 'python', 'default')) parsed_docs = [(doc.parse(), doc.marker, doc.indent, doc.position) for doc in original] docstyle_definition = DocstyleDefinition.load('python', 'default') assembled_docs = [DocumentationComment.from_metadata( doc[0], docstyle_definition, doc[1], doc[2], doc[3]) for doc in parsed_docs] self.assertEqual(assembled_docs, original)
def test_DocBaseClass_instantiate_padding_inline_PYTHON3_9(self): # Paddings will not be instantiated for docstring_type=others data = ['\n', ' """\n', ' documentation in single line\n', ' """ # This is inline docstring', '\n', '\n', 'print(1)'] docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3', 'default') for doc in DocBaseClass.extract(data, 'PYTHON3', 'default'): self.assertEqual([doc.top_padding, doc.bottom_padding], [0, 0])
def test_DocBaseClass_instantiate_padding_inline_PYTHON3_8(self): # To test that bottom_padding sets to nothing if docstring is # followed by inline docstring. data = ['def some_function:\n', '\n', ' """\n', ' documentation in single line\n', ' """ # This is inline docstring', '\n', '\n', 'print(1)'] docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3', 'default') for doc in DocBaseClass.extract(data, 'PYTHON3', 'default'): self.assertEqual([doc.top_padding, doc.bottom_padding], [1, 0])
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(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)