Permalink
Browse files

DocumentationStyleBear: Add expand_one_liners

Add expand_one_liners setting which will expand one
liners to multi line docstring.

Closes #1856
  • Loading branch information...
damngamerz committed Jul 22, 2017
1 parent 314dfdf commit 40cd08676593e44dc1fc34b18e89e4529aa454ae
@@ -20,8 +20,11 @@ class DocumentationStyleBear(DocBaseClass, LocalBear):
CAN_DETECT = {'Documentation'}
CAN_FIX = {'Documentation'}
def process_documentation(self, parsed, allow_missing_func_desc: str=False,
indent_size: int=4):
def process_documentation(self,
parsed,
allow_missing_func_desc: str=False,
indent_size: int=4,
expand_one_liners: str=False):
"""
This fixes the parsed documentation comment.
@@ -32,6 +35,8 @@ def process_documentation(self, parsed, allow_missing_func_desc: str=False,
descriptions, allowing functions to start with params.
:param indent_size:
Number of spaces per indentation level.
:param expand_one_liners:
When set ``True`` this will expand one liner docstrings.
:return:
A tuple of fixed parsed documentation comment and warning_desc.
"""
@@ -54,9 +59,13 @@ def process_documentation(self, parsed, allow_missing_func_desc: str=False,
# one empty line shall follow main description (except it's empty
# or no annotations follow).
if main_description.desc.strip() != '':
main_description = main_description._replace(
desc='\n' + main_description.desc.strip() + '\n' *
(1 if len(parsed) == 1 else 2))
if not expand_one_liners and len(parsed) == 1:
main_description = main_description._replace(
desc=main_description.desc.strip())
else:
main_description = main_description._replace(
desc='\n' + main_description.desc.strip() + '\n' *
(1 if len(parsed) == 1 else 2))
new_metadata = [main_description]
for m in metadata:
@@ -87,7 +96,7 @@ def process_documentation(self, parsed, allow_missing_func_desc: str=False,
def run(self, filename, file, language: str,
docstyle: str='default', allow_missing_func_desc: str=False,
indent_size: int=4):
indent_size: int=4, expand_one_liners: str=False):
"""
Checks for certain in-code documentation styles.
@@ -110,13 +119,16 @@ def run(self, filename, file, language: str,
functions with missing descriptions, allowing
functions to start with params.
:param indent_size: Number of spaces per indentation level.
:param expand_one_liners: When set ``True`` this will expand one liner
docstrings.
"""
for doc_comment in self.extract(file, language, docstyle):
parsed = doc_comment.parse()
(new_metadata, warning_desc) = self.process_documentation(
parsed, allow_missing_func_desc, indent_size)
parsed, allow_missing_func_desc, indent_size,
expand_one_liners)
new_comment = DocumentationComment.from_metadata(
new_metadata, doc_comment.docstyle_definition,
@@ -16,13 +16,13 @@ def load_testfile(filename):
return fl.read()
def test(test_file, expected_file):
def test(test_file, expected_file, optional_setting=None):
def test_function(self):
test_file_content = load_testfile(test_file).splitlines(True)
arguments = {'language': 'python', 'docstyle': 'default'}
if test_file == 'good_file3.py.test':
arguments.update({'allow_missing_func_desc': 'True'})
if optional_setting:
arguments.update(optional_setting)
section = Section('test-section')
for key, value in arguments.items():
section[key] = value
@@ -49,10 +49,13 @@ def test_function(self):
class DocumentationStyleBearTest(unittest.TestCase):
test_bad1 = test('bad_file.py.test', 'bad_file.py.test.correct')
test_bad2 = test('bad_file2.py.test', 'bad_file2.py.test.correct')
test_bad3 = test('bad_file3.py.test', 'bad_file3.py.test.correct')
test_bad2 = test('bad_file2.py.test', 'bad_file2.py.test.correct',
{'expand_one_liners': 'True'})
test_bad3 = test('bad_file3.py.test', 'bad_file3.py.test.correct',
{'expand_one_liners': 'True'})
test_bad4 = test('bad_file4.py.test', 'bad_file4.py.test.correct')
test_bad5 = test('bad_file5.py.test', 'bad_file5.py.test.correct')
test_good1 = test('good_file.py.test', 'good_file.py.test')
test_good2 = test('good_file2.py.test', 'good_file2.py.test')
test_good3 = test('good_file3.py.test', 'good_file3.py.test')
test_good3 = test('good_file3.py.test', 'good_file3.py.test',
{'allow_missing_func_desc': 'True'})
@@ -7,3 +7,12 @@ def docstring_improper_alignment():
:param x:
:return:
""" return None
""" This is one liner having extra whitespaces """
"""
This is malformed one liner docstring"""
"""
This is multi-liner docstring
"""
@@ -7,3 +7,9 @@ def docstring_improper_alignment():
:param x:
:return:
""" return None
"""This is one liner having extra whitespaces"""
"""This is malformed one liner docstring"""
"""This is multi-liner docstring"""
@@ -4,3 +4,5 @@ def docstring_missing_description(dummy):
a function starting with `param`
in this case allow_missing_func_desc = True
"""
"""This is one-liner docstring"""

0 comments on commit 40cd086

Please sign in to comment.