DocumentationStyleBear: Add expand_one_liners

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

Closes #1856

Author: damngamerz

bears/documentation/DocumentationStyleBear.py

@@ -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,

tests/documentation/DocumentationStyleBearTest.py

@@ -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'})

tests/documentation/test_files/DocumentationStyleBear/bad_file5.py.test

@@ -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
+"""

tests/documentation/test_files/DocumentationStyleBear/bad_file5.py.test.correct

@@ -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"""

tests/documentation/test_files/DocumentationStyleBear/good_file3.py.test

@@ -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"""