require Return section only if return is not None nor commentary

scripts/tests/test_validate_docstrings.py

@@ -229,6 +229,27 @@ def good_imports(self):
         """
         pass
 
+    def no_returns(self):
+        """
+        Say hello and have no returns.
+        """
+        print("Hello World!")
+
+    def empty_returns(self):
+        """
+        Say hello and always return None.
+
+        Since this function never returns a value, this
+        docstring doesn't need a return section.
+        """
+        def say_hello():
+            return "Hello World!"
+        say_hello()
+        if True:
+            return
+        else:
+            return None
+
 
 class BadGenericDocStrings(object):
     """Everything here has a bad docstring
@@ -594,7 +615,10 @@ def return_not_documented(self):
         """
         Lacks section for Returns
         """
-        return "Hello world!"
+        if False:
+            return None
+        else:
+            return True
 
     def yield_not_documented(self):
         """
@@ -783,7 +807,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', 'no_returns', 'empty_returns'])
     def test_good_functions(self, capsys, func):
         errors = validate_one(self._import_path(
             klass='GoodDocStrings', func=func))['errors']

scripts/validate_docstrings.py

@@ -26,6 +26,7 @@
 import importlib
 import doctest
 import tempfile
+import ast
 
 import flake8.main.application
 
@@ -490,10 +491,41 @@ def yields(self):
     @property
     def method_source(self):
         try:
-            return inspect.getsource(self.obj)
+            source = inspect.getsource(self.obj)
+            # Remove common indentation.
+            first_spaces = re.match(' +', source)
+            if first_spaces:
+                first_spaces = first_spaces.group(0)
+                source = re.sub('^' + first_spaces, '', source)
+                source = re.sub(r'\n' + first_spaces, r'\n', source)
+            return source
         except TypeError:
             return ''
 
+    @property
+    def method_returns(self):
+        tree = ast.parse(self.method_source).body
+        if tree:
+            root = tree[0]
+
+            def gather_returns(node):
+                gathered = [node] if isinstance(node, ast.Return) else []
+                for child in ast.iter_child_nodes(node):
+                    # Ignore nested functions and its subtrees.
+                    if not isinstance(child, ast.FunctionDef):
+                        gathered.extend(gather_returns(child))
+                return gathered
+            # Walk the tree recursively and gather the return nodes.
+            return_values = [r.value for r in gather_returns(root)]
+
+            # Replace NameConstant nodes valued None for None.
+            for i, v in enumerate(return_values):
+                if isinstance(v, ast.NameConstant) and v.value is None:
+                    return_values[i] = None
+            return return_values
+        else:
+            return []
+
     @property
     def first_line_ends_in_dot(self):
         if self.doc:
@@ -691,7 +723,7 @@ def get_validation_data(doc):
 
     if doc.is_function_or_method:
         if not doc.returns:
-            if 'return' in doc.method_source:
+            if any(ret is not None for ret in doc.method_returns):
                 errs.append(error('RT01'))
         else:
             if len(doc.returns) == 1 and doc.returns[0][1]: