DocumentationStyleBear: Add blankline support

DocumentationStyleBear now checks for blankline before and after the docstring and fixes them. Related to coala/coala#4200
coala · Aug 19, 2017 · 89b5913837d54279a928d3ef3c62995f4e9c2648 · 89b5913
1 parent 1e451a2
commit 89b5913837d54279a928d3ef3c62995f4e9c2648
diff --git a/bears/documentation/DocumentationStyleBear.py b/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(
diff --git a/tests/documentation/DocumentationStyleBearTest.py b/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',
diff --git a/tests/documentation/test_files/DocumentationStyleBear/bad_file.java.test b/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;
+    }
+}
diff --git a/tests/documentation/test_files/DocumentationStyleBear/bad_file.java.test.correct b/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;
+    }
+}
diff --git a/tests/documentation/test_files/DocumentationStyleBear/bad_file2.py.test b/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():
    """
diff --git a/tests/documentation/test_files/DocumentationStyleBear/bad_file2.py.test.correct b/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():
    """
diff --git a/tests/documentation/test_files/DocumentationStyleBear/bad_file3.py.test b/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):
diff --git a/tests/documentation/test_files/DocumentationStyleBear/bad_file3.py.test.correct b/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):
diff --git a/tests/documentation/test_files/DocumentationStyleBear/bad_file4.py.test b/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
diff --git a/tests/documentation/test_files/DocumentationStyleBear/bad_file4.py.test.correct b/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
diff --git a/tests/documentation/test_files/DocumentationStyleBear/good_file3.py.test b/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"""