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_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_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_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_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 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(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_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_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', docstyle_C_doxygen,
'', docstyle_C_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_load_external_coalang(self):
empty_metadata = self.Metadata('', '', '')
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, (('@@', '@@', '@@'), ))
self.assertEqual(result.metadata, empty_metadata)
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_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 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(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_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_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_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)
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],
TextRange.from_values(4, 1, 8, 4)),
DocumentationComment(
(' foobar\n'
' @param xyz\n'),
docstyle_CPP_doxygen, '',
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(15, 1, 17, 4)),
DocumentationComment(
' Some alternate style of documentation\n',
docstyle_CPP_doxygen, '',
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(22, 1, 23, 1)),
DocumentationComment(
' ends instantly',
docstyle_CPP_doxygen, '\t',
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(26, 2, 26, 23)),
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],
TextRange.from_values(32, 1, 37, 1))))
