def test_DocBaseClass_extraction_CPP(self):
data = load_testdata('data.cpp')
# No built-in documentation for C++.
with self.assertRaises(KeyError):
tuple(DocBaseClass.extract(data, 'CPP', 'default'))
docstyle_CPP_doxygen = DocstyleDefinition.load('CPP', 'doxygen')
self.assertEqual(
tuple(DocBaseClass.extract(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_python_doxygen(self):
data = load_testdata('doxygen.py')
parsed_docs = [doc.parse() for doc in
DocBaseClass.extract(data, 'python', 'doxygen')]
expected = [
[self.Description(desc=' @package pyexample\n Documentation for'
' this module.\n\n More details.\n')],
[self.Description(
desc=' Documentation for a class.\n\n More details.\n')],
[self.Description(desc=' The constructor.\n')],
[self.Description(desc=' Documentation for a method.\n'),
self.Parameter(name='self', desc='The object pointer.\n')],
[self.Description(desc=' A class variable.\n')],
[self.Description(desc=' @var _memVar\n a member variable\n')],
[self.Description(desc=' This is the best docstring ever!\n\n'),
self.Parameter(name='param1', desc='Parameter 1\n'),
self.Parameter(name='param2', desc='Parameter 2\n'),
self.ReturnValue(desc='Nothing\n')],
[self.Description(desc=' This is dummy docstring find '
'function.\n\n'),
self.Parameter(name='filename', desc='contains filename\n'),
self.ExceptionValue(name='FileNotFoundError',
desc='raises when filename is not found\n'),
self.ReturnValue(desc='nothing\n')],
]
self.assertEqual(parsed_docs, expected)
def test_java_default(self):
data = load_testdata('default.java')
parsed_docs = [
doc.parse()
for doc in DocBaseClass.extract(data, 'java', 'default')
]
expected = [
[
self.Description(
desc='\n Returns an String that says Hello with the name'
' argument.\n\n'),
self.Parameter(name='name',
desc='the name to which to say hello\n'),
self.ExceptionValue(name='IOException',
desc='throws IOException\n'),
self.ReturnValue(desc=' the concatenated string\n')
],
[
self.Description(desc='\n Returns Area of a square.\n\n'),
self.Parameter(name='side', desc='side of square\n'),
self.ReturnValue(desc=' area of a square\n')
],
]
self.assertEqual(expected, parsed_docs)
def test_python_doxygen(self):
data = load_testdata('doxygen.py')
parsed_docs = [doc.parse() for doc in
DocBaseClass.extract(data, 'python', 'doxygen')]
expected = [
[self.Description(desc=' @package pyexample\n Documentation for'
' this module.\n\n More details.\n')],
[self.Description(
desc=' Documentation for a class.\n\n More details.\n')],
[self.Description(desc=' The constructor.\n')],
[self.Description(desc=' Documentation for a method.\n'),
self.Parameter(name='self', desc='The object pointer.\n')],
[self.Description(desc=' A class variable.\n')],
[self.Description(desc=' @var _memVar\n a member variable\n')],
[self.Description(desc=' This is the best docstring ever!\n\n'),
self.Parameter(name='param1', desc='Parameter 1\n'),
self.Parameter(name='param2', desc='Parameter 2\n'),
self.ReturnValue(desc='Nothing\n')],
[self.Description(desc=' This is dummy docstring find '
'function.\n\n'),
self.Parameter(name='filename', desc='contains filename\n'),
self.ExceptionValue(name='FileNotFoundError',
desc='raises when filename is not found\n'),
self.ReturnValue(desc='nothing\n')],
]
self.assertEqual(parsed_docs, expected)
def test_python_assembly(self):
data = load_testdata('default.py')
docs = ''.join(data)
for doc in DocBaseClass.extract(data, 'python', 'default'):
doc.bottom_padding = 2
doc.assemble.cache_clear()
self.assertIn(doc.assemble(), docs)
def test_c_assembly(self):
data = load_testdata('default.c')
docs = ''.join(data)
for doc in DocBaseClass.extract(data, 'c', 'doxygen'):
doc.top_padding = 1
doc.assemble.cache_clear()
self.assertIn(doc.assemble(), docs)
def test_c_assembly(self):
data = load_testdata('default.c')
docs = ''.join(data)
for doc in DocBaseClass.extract(data, 'c', 'doxygen'):
doc.top_padding = 1
doc.assemble.cache_clear()
self.assertIn(doc.assemble(), docs)
def test_python_default_padding_amend_assembly_2(self):
data = ['""" documentation in single line """\n']
for doc in DocBaseClass.extract(data, 'python', 'default'):
doc.top_padding = 2
doc.bottom_padding = 3
doc.assemble.cache_clear()
self.assertEqual(doc.assemble(),
'\n\n""" documentation in single line """\n\n\n')
def test_python_default_padding_amend_assembly_2(self):
data = ['""" documentation in single line """\n']
for doc in DocBaseClass.extract(data, 'python', 'default'):
doc.top_padding = 2
doc.bottom_padding = 3
doc.assemble.cache_clear()
self.assertEqual(doc.assemble(),
'\n\n""" documentation in single line """\n\n\n')
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_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_python_doxygen_padding_amend_assembly(self):
data = ['## documentation in single line without return at end.']
for doc in DocBaseClass.extract(data, 'python', 'doxygen'):
doc.top_padding = 0
doc.bottom_padding = 2
doc.assemble.cache_clear()
self.assertEqual(doc.assemble(),
'## documentation in single line '
'without return at end.\n\n')
def test_DocBaseClass_extraction_CPP(self):
data = load_testdata('data.cpp')
# No built-in documentation for C++.
with self.assertRaises(KeyError):
tuple(DocBaseClass.extract(data, 'CPP', 'default'))
docstyle_CPP_doxygen = DocstyleDefinition.load('CPP', 'doxygen')
self.assertEqual(tuple(DocBaseClass.extract(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_python_doxygen_padding_amend_assembly(self):
data = ['## documentation in single line without return at end.']
for doc in DocBaseClass.extract(data, 'python', 'doxygen'):
doc.top_padding = 0
doc.bottom_padding = 2
doc.assemble.cache_clear()
self.assertEqual(
doc.assemble(), '## documentation in single line '
'without return at end.\n\n')
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_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_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_c_default_padding_amend_assembly(self):
data = ['/**\n', ' * This is the main function.\n', ' */\n']
for doc in DocBaseClass.extract(data, 'c', 'doxygen'):
doc.top_padding = 1
doc.bottom_padding = 2
doc.assemble.cache_clear()
self.assertEqual(
doc.assemble(), '\n/**\n'
' * This is the main function.\n'
' */\n\n')
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_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_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_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_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_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_MalformedComment2_CPP(self):
data = ['\n', '/** Aborts...\n']
expected = [
dedent("""\
Please check the docstring for faulty markers. A starting
marker has been found, but no instance of DocComment is
returned."""), 1
]
for doc_comment in DocBaseClass.extract(data, 'CPP', 'doxygen'):
self.assertEqual([doc_comment.message, doc_comment.line], expected)
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_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_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_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_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_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_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_MalformedComment3_JAVA(self):
data = ['/**\n', '* Markers are faulty\n', '*/']
expected = [
dedent("""\
Please check the docstring for faulty markers. A starting
marker has been found, but no instance of DocComment is
returned."""), 0
]
for doc_comment in DocBaseClass.extract(data, 'JAVA', 'default'):
self.assertEqual([doc_comment.message, doc_comment.line], expected)
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_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_c_default_padding_amend_assembly(self):
data = ['/**\n',
' * This is the main function.\n',
' */\n']
for doc in DocBaseClass.extract(data, 'c', 'doxygen'):
doc.top_padding = 1
doc.bottom_padding = 2
doc.assemble.cache_clear()
self.assertEqual(doc.assemble(),
'\n/**\n'
' * This is the main function.\n'
' */\n\n')
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_generate_diff(self):
data_old = ['\n', '""" documentation in single line """\n']
for doc_comment in DocBaseClass.extract(data_old, 'PYTHON3',
'default'):
old_doc_comment = doc_comment
old_range = TextRange.from_values(old_doc_comment.range.start.line, 1,
old_doc_comment.range.end.line,
old_doc_comment.range.end.column)
data_new = ['\n', '"""\n documentation in single line\n"""\n']
for doc_comment in DocBaseClass.extract(data_new, 'PYTHON3',
'default'):
new_doc_comment = doc_comment
diff = DocBaseClass.generate_diff(data_old, old_doc_comment,
new_doc_comment)
diff_expected = Diff(data_old)
diff_expected.replace(old_range, new_doc_comment.assemble())
self.assertEqual(diff, diff_expected)
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_MalformedComment2_CPP(self):
data = ['\n',
'/** Aborts...\n']
expected = [dedent("""\
Please check the docstring for faulty markers. A starting
marker has been found, but no instance of DocComment is
returned."""), 1]
for doc_comment in DocBaseClass.extract(data, 'CPP', 'doxygen'):
self.assertEqual(
[doc_comment.message, doc_comment.line],
expected)
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_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_MalformedComment3_JAVA(self):
data = ['/**\n',
'* Markers are faulty\n',
'*/']
expected = [dedent("""\
Please check the docstring for faulty markers. A starting
marker has been found, but no instance of DocComment is
returned."""), 0]
for doc_comment in DocBaseClass.extract(data, 'JAVA', 'default'):
self.assertEqual(
[doc_comment.message, doc_comment.line],
expected)
def test_MalformedComment1_C(self):
data = ['/**\n',
'* A doc-comment aborted in the middle of writing\n',
'* This won\'t get parsed (hopefully...)\n']
expected = [dedent("""\
Please check the docstring for faulty markers. A starting
marker has been found, but no instance of DocComment is
returned."""), 0]
for doc_comment in DocBaseClass.extract(data, 'C', 'doxygen'):
self.assertEqual(
[doc_comment.message, doc_comment.line],
expected)
def test_go_default(self):
data = load_testdata('default.go')
parsed_docs = [doc.parse() for doc in
DocBaseClass.extract(data, 'golang', 'golang')]
expected = [['\n',
'Comments may span\n',
'multiple lines\n'],
['A class comment\n',
'that also spans\n',
'multiple lines\n'],
['More documentation for everyone, but in one line\n']]
self.assertEqual(expected, parsed_docs)
def test_MalformedComment1_C(self):
data = [
'/**\n', '* A doc-comment aborted in the middle of writing\n',
'* This won\'t get parsed (hopefully...)\n'
]
expected = [
dedent("""\
Please check the docstring for faulty markers. A starting
marker has been found, but no instance of DocComment is
returned."""), 0
]
for doc_comment in DocBaseClass.extract(data, 'C', 'doxygen'):
self.assertEqual([doc_comment.message, doc_comment.line], expected)
def test_generate_diff(self):
data_old = ['\n', '""" documentation in single line """\n']
for doc_comment in DocBaseClass.extract(
data_old, 'PYTHON3', 'default'):
old_doc_comment = doc_comment
old_range = TextRange.from_values(
old_doc_comment.range.start.line,
1,
old_doc_comment.range.end.line,
old_doc_comment.range.end.column)
data_new = ['\n', '"""\n documentation in single line\n"""\n']
for doc_comment in DocBaseClass.extract(
data_new, 'PYTHON3', 'default'):
new_doc_comment = doc_comment
diff = DocBaseClass.generate_diff(
data_old, old_doc_comment, new_doc_comment)
diff_expected = Diff(data_old)
diff_expected.replace(old_range, new_doc_comment.assemble())
self.assertEqual(diff, diff_expected)
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_go_default(self):
data = load_testdata('default.go')
parsed_docs = [doc.parse() for doc in
DocBaseClass.extract(data, 'golang', 'golang')]
expected = [['\n',
'Comments may span\n',
'multiple lines\n'],
['A class comment\n',
'that also spans\n',
'multiple lines\n'],
['More documentation for everyone, but in one line\n']]
self.assertEqual(expected, parsed_docs)
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_python_default(self):
data = load_testdata('default.py')
parsed_docs = [doc.parse() for doc in
DocBaseClass.extract(data, 'python', 'default')]
expected = [
[self.Description(desc='\nModule description.\n\n'
'Some more foobar-like text.\n')],
[self.Description(desc='\nA nice and neat way of '
'documenting code.\n'),
self.Parameter(name='radius', desc=' The explosion radius. ')],
[self.Description(desc='A function that returns 55.')],
[self.Description(desc='\nDocstring with layouted text.\n\n '
'layouts inside docs are preserved.'
'\nthis is intended.\n')],
[self.Description(desc=' Docstring inline with triple quotes.\n'
' Continues here. ')],
[self.Description(desc='\nThis is the best docstring ever!\n\n'),
self.Parameter(name='param1',
desc='\n Very Very Long Parameter '
'description.\n'),
self.Parameter(name='param2',
desc='\n Short Param description.\n\n'),
self.ReturnValue(desc=' Long Return Description That Makes No '
'Sense And Will\n Cut to the Next'
' Line.\n')],
[self.Description(desc='\nThis is dummy docstring find '
'function.\n\n'),
self.Parameter(name='filename',
desc='\n contains filename\n'),
self.ExceptionValue(name='FileNotFoundError',
desc='\n raised when the given '
'file name was not found\n\n'),
self.ReturnValue(desc=' returns all possible docstrings'
' in a file\n')],
[self.Description(desc='\nThis returns perimeter '
'of a triangle. \n\n'),
self.Parameter(name='side_A',
desc='\n length of side_A \n'),
self.Parameter(name='side_B',
desc='\n length of side_B \n'),
self.Parameter(name='side_C',
desc='\n length of side_C \n\n'),
self.ReturnValue(desc=' returns perimeter\n')],
]
self.assertEqual(parsed_docs, expected)
def test_python_default(self):
data = load_testdata('default.py')
parsed_docs = [doc.parse() for doc in
DocBaseClass.extract(data, 'python', 'default')]
expected = [
[self.Description(desc='\nModule description.\n\n'
'Some more foobar-like text.\n')],
[self.Description(desc='\nA nice and neat way of '
'documenting code.\n'),
self.Parameter(name='radius', desc=' The explosion radius. ')],
[self.Description(desc='A function that returns 55.')],
[self.Description(desc='\nDocstring with layouted text.\n\n '
'layouts inside docs are preserved.'
'\nthis is intended.\n')],
[self.Description(desc=' Docstring inline with triple quotes.\n'
' Continues here. ')],
[self.Description(desc='\nThis is the best docstring ever!\n\n'),
self.Parameter(name='param1',
desc='\n Very Very Long Parameter '
'description.\n'),
self.Parameter(name='param2',
desc='\n Short Param description.\n\n'),
self.ReturnValue(desc=' Long Return Description That Makes No '
'Sense And Will\n Cut to the Next'
' Line.\n')],
[self.Description(desc='\nThis is dummy docstring find '
'function.\n\n'),
self.Parameter(name='filename',
desc='\n contains filename\n'),
self.ExceptionValue(name='FileNotFoundError',
desc='\n raised when the given '
'file name was not found\n\n'),
self.ReturnValue(desc=' returns all possible docstrings'
' in a file\n')],
[self.Description(desc='\nThis returns perimeter '
'of a triangle. \n\n'),
self.Parameter(name='side_A',
desc='\n length of side_A \n'),
self.Parameter(name='side_B',
desc='\n length of side_B \n'),
self.Parameter(name='side_C',
desc='\n length of side_C \n\n'),
self.ReturnValue(desc=' returns perimeter\n')],
]
self.assertEqual(parsed_docs, expected)
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_java_default(self):
data = load_testdata('default.java')
parsed_docs = [doc.parse() for doc in
DocBaseClass.extract(data, 'java', 'default')]
expected = [[self.Description(
desc='\n Returns an String that says Hello with the name'
' argument.\n\n'),
self.Parameter(name='name',
desc='the name to which to say hello\n'),
self.ExceptionValue(name='IOException',
desc='throws IOException\n'),
self.ReturnValue(
desc=' the concatenated string\n')]]
self.assertEqual(expected, parsed_docs)
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_c_assembly(self):
data = load_testdata('default.c')
docs = ''.join(data)
for doc in DocBaseClass.extract(data, 'c', 'doxygen'):
self.assertIn(doc.assemble(), docs)
def test_DocBaseClass_extraction_invalid_input(self):
with self.assertRaises(FileNotFoundError):
tuple(DocBaseClass.extract('', 'PYTHON', 'INVALID'))
def test_doxygen_assembly(self):
data = load_testdata('doxygen.py')
docs = ''.join(data)
for doc in DocBaseClass.extract(data, 'python', 'doxygen'):
self.assertIn(doc.assemble(), docs)
