require Return section only if return is not None nor commentary

scripts/tests/test_validate_docstrings.py

@@ -229,6 +229,24 @@ def good_imports(self):
         """
         pass
 
+    def does_nothing(self, x):
+        """
+        Do nothing and always return none.
+
+        But in other cases it might also
+        return nothing at all.
+
+        Parameters
+        ----------
+        x : int
+            Useless parameter.
+        """
+        var_with_return_on_the_name = random.random()
+        if var_with_return_on_the_name % 2:
+            return  # the method might return here
+        else:
+            return None  # or perhaps here
+
 
 class BadGenericDocStrings(object):
     """Everything here has a bad docstring
@@ -594,7 +612,10 @@ def return_not_documented(self):
         """
         Lacks section for Returns
         """
-        return "Hello world!"
+        if random.random() % 2:
+            return None
+        else:
+            return "Hello world!"
 
     def yield_not_documented(self):
         """
@@ -783,7 +804,7 @@ def test_good_class(self, capsys):
 
     @pytest.mark.parametrize("func", [
         'plot', 'sample', 'random_letters', 'sample_values', 'head', 'head1',
-        'contains', 'mode', 'good_imports'])
+        'contains', 'mode', 'good_imports', 'does_nothing'])
     def test_good_functions(self, capsys, func):
         errors = validate_one(self._import_path(
             klass='GoodDocStrings', func=func))['errors']

scripts/validate_docstrings.py

@@ -494,6 +494,15 @@ def method_source(self):
         except TypeError:
             return ''
 
+    @property
+    def clean_method_source(self):
+        src = self.method_source
+        src = re.sub(r'""".*"""', '', src, 0, re.DOTALL)  # Remove docstring.
+        src = re.sub(r'#.*\n', r'\n', src)  # Remove comments.
+        src = re.sub(r' +', ' ', src)  # Remove duplicate whitespaces.
+        src = re.sub(r' \n', r'\n', src)  # Remove trailing whitespaces.
+        return src
+
     @property
     def first_line_ends_in_dot(self):
         if self.doc:
@@ -691,7 +700,7 @@ def get_validation_data(doc):
 
     if doc.is_function_or_method:
         if not doc.returns:
-            if 'return' in doc.method_source:
+            if re.search(r"\breturn\b(?!( None)?\n)", doc.clean_method_source):
                 errs.append(error('RT01'))
         else:
             if len(doc.returns) == 1 and doc.returns[0][1]: