DocumentationStyleBear: Add blankline support

DocumentationStyleBear now checks for blankline
before and after the docstring and fixes them.

Related to coala/coala#4200

Author: damngamerz

bears/documentation/DocumentationStyleBear.py

@@ -21,15 +21,15 @@ class DocumentationStyleBear(DocBaseClass, LocalBear):
     CAN_FIX = {'Documentation'}
 
     def process_documentation(self,
-                              parsed,
+                              doc_comment: DocumentationComment,
                               allow_missing_func_desc: str=False,
                               indent_size: int=4,
                               expand_one_liners: str=False):
         """
         This fixes the parsed documentation comment.
 
-        :param parsed:
-            Contains parsed documentation comment.
+        :param doc_comment:
+            Contains instance of DocumentationComment.
         :param allow_missing_func_desc:
             When set ``True`` this will allow functions with missing
             descriptions, allowing functions to start with params.
@@ -40,6 +40,7 @@ def process_documentation(self,
         :return:
             A tuple of fixed parsed documentation comment and warning_desc.
         """
+        parsed = doc_comment.parse()
         # Assuming that the first element is always the only main
         # description.
         metadata = iter(parsed)
@@ -92,7 +93,36 @@ def process_documentation(self,
             new_desc = new_desc.rstrip() + '\n'
 
             new_metadata.append(m._replace(desc=new_desc.lstrip(' ')))
-        return (new_metadata, warning_desc)
+
+        new_comment = DocumentationComment.from_metadata(
+            new_metadata, doc_comment.docstyle_definition,
+            doc_comment.marker, doc_comment.indent, doc_comment.position)
+
+        # Instantiate default padding.
+        class_padding = doc_comment.docstyle_definition.class_padding
+        function_padding = doc_comment.docstyle_definition.function_padding
+        # Check if default padding exist in the coalang file.
+        if (class_padding != DocstyleDefinition.ClassPadding('', '') and
+                function_padding != DocstyleDefinition.FunctionPadding(
+                    '', '')):
+            # Check docstring_type
+            if doc_comment.docstring_type == 'class':
+                new_comment.top_padding = class_padding.top_padding
+                new_comment.bottom_padding = class_padding.bottom_padding
+            elif doc_comment.docstring_type == 'function':
+                new_comment.top_padding = function_padding.top_padding
+                new_comment.bottom_padding = function_padding.bottom_padding
+            else:
+                # Keep paddings as they are originally.
+                new_comment.top_padding = doc_comment.top_padding
+                new_comment.bottom_padding = doc_comment.bottom_padding
+        else:
+            # If there's no default paddings defined. Keep padding as
+            # they are originally.
+            new_comment.top_padding = doc_comment.top_padding
+            new_comment.bottom_padding = doc_comment.bottom_padding
+
+        return (new_comment, warning_desc)
 
     def run(self, filename, file, language: str,
             docstyle: str='default', allow_missing_func_desc: str=False,
@@ -131,18 +161,15 @@ def run(self, filename, file, language: str,
                     file=filename,
                     line=doc_comment.line + 1)
             else:
-                parsed = doc_comment.parse()
-
-                (new_metadata, warning_desc) = self.process_documentation(
-                            parsed, allow_missing_func_desc, indent_size,
-                            expand_one_liners)
-
-                new_comment = DocumentationComment.from_metadata(
-                    new_metadata, doc_comment.docstyle_definition,
-                    doc_comment.marker, doc_comment.indent,
-                    doc_comment.position)
-
-                if new_comment != doc_comment:
+                (new_comment, warning_desc) = self.process_documentation(
+                                doc_comment, allow_missing_func_desc,
+                                indent_size, expand_one_liners)
+
+                # Cache cleared so a fresh docstring is assembled
+                doc_comment.assemble.cache_clear()
+                # Assembled docstring check, because paddings are only
+                # amended after assemble()
+                if new_comment.assemble() != doc_comment.assemble():
                     # Something changed, let's apply a result.
                     diff = self.generate_diff(file, doc_comment, new_comment)
                     yield Result(

tests/documentation/DocumentationStyleBearTest.py

@@ -78,6 +78,8 @@ class DocumentationStyleBearTest(unittest.TestCase):
     test_good2 = test('good_file2.py.test', 'good_file2.py.test')
     test_good3 = test('good_file3.py.test', 'good_file3.py.test',
                       {'allow_missing_func_desc': 'True'})
+    test_bad_java = test('bad_file.java.test', 'bad_file.java.test.correct',
+                         {'language': 'java'})
 
     test_malformed_comment_python = test_MalformedComment(
         ['"""\n',

tests/documentation/test_files/DocumentationStyleBear/bad_file.java.test

@@ -0,0 +1,15 @@
+class HelloWorld {
+
+   /**
+    *Java docstyle test.
+    *There's no official standard for how paddings are in java.
+    *Hence, in this case paddings are preserved as original.
+    *
+    *@param  name the name to which to say hello
+    *@raises  IOException throws IOException
+    *@return      the concatenated string
+    */
+    public String sayHello(String name) throws IOException {
+        return "Hello, " + name;
+    }
+}

tests/documentation/test_files/DocumentationStyleBear/bad_file.java.test.correct

@@ -0,0 +1,18 @@
+class HelloWorld {
+
+   /**
+    *Java docstyle test.
+    *There's no official standard for how paddings are in java.
+    *Hence, in this case paddings are preserved as original.
+    *
+    *@param  name 
+    *    the name to which to say hello
+    *@raises  IOException 
+    *    throws IOException
+    *@return 
+    *    the concatenated string
+    */
+    public String sayHello(String name) throws IOException {
+        return "Hello, " + name;
+    }
+}

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

@@ -14,6 +14,7 @@ def docstring_testcase(dummy):
 def docstring_singleliner():
     """ This is singleliner docstring. """
 
+    return None
 
 def docstring_inline():
     """

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

@@ -17,7 +17,7 @@ def docstring_singleliner():
     """
     This is singleliner docstring.
     """
-
+    return None
 
 def docstring_inline():
     """

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

@@ -30,9 +30,11 @@ class docstring_if_indented():
             """
             This is `if` indented block function.
             """
+            return None
     else:
         def hello_venus(self):
             """This is `if` indented block function."""
+            return None
 
 
 def docstring_inner_function(dummy):

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

@@ -41,11 +41,13 @@ class docstring_if_indented():
             """
             This is `if` indented block function.
             """
+            return None
     else:
         def hello_venus(self):
             """
             This is `if` indented block function.
             """
+            return None
 
 
 def docstring_inner_function(dummy):

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

@@ -7,3 +7,28 @@ def docstring_missing_descriptions(a, b, x):
     :return:"""
 
     return a * x + b
+
+
+class docstring_class_improper_paddings(dummy):
+
+    """
+    Docstring has improper paddings. `class` type docstrings
+    should be followed by 1 blank line at the bottom.
+
+    :param dummy:
+        dummy description.
+    """
+
+
+    def docstring_function_improper_paddings:
+
+        """
+        Docstring has improper paddings. `function` type docstrings
+        should never be followed by any blank lines.
+
+        :return:
+            None
+        """
+
+
+        return None

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

@@ -8,5 +8,24 @@ def docstring_missing_descriptions(a, b, x):
     :param x:
     :return:
     """
-
     return a * x + b
+
+
+class docstring_class_improper_paddings(dummy):
+    """
+    Docstring has improper paddings. `class` type docstrings
+    should be followed by 1 blank line at the bottom.
+
+    :param dummy:
+        dummy description.
+    """
+
+    def docstring_function_improper_paddings:
+        """
+        Docstring has improper paddings. `function` type docstrings
+        should never be followed by any blank lines.
+
+        :return:
+            None
+        """
+        return None

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

@@ -4,5 +4,6 @@ def docstring_missing_description(dummy):
         a function starting with `param`
         in this case allow_missing_func_desc = True
     """
+    return None
 
 """This is one-liner docstring"""