Merge pull request #86 from twisted/no-inner-doc-requirement

Allow classes defined within functions to be undocumented.

Author: glyph

setup.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-
+# -*- test-case-name: twistedchecker -*-
 # Copyright (c) Twisted Matrix Laboratories.
 # See LICENSE for details.
 

twistedchecker/checkers/docstring.py

@@ -1,3 +1,11 @@
+# -*- test-case-name: twistedchecker.test.test_functionaltests -*-
+# Copyright (c) Twisted Matrix Laboratories.
+# See LICENSE for details.
+
+"""
+Checks for docstrings.
+"""
+
 import re
 
 from logilab.astng import node_classes
@@ -8,6 +16,24 @@
 from pylint.checkers.base import NO_REQUIRED_DOC_RGX
 
 
+def _isInner(node):
+    """
+    Determine whether the given node is, at any point in its syntactic
+    parentage, defined within a function.
+
+    @param node: The node to inspect.
+    @type node: L{logilab.astng.bases.NodeNG}
+
+    @return: a boolean indicating if the given node is defined as an inner
+        class or inner function.
+    """
+    while node:
+        node = node.parent
+        if isinstance(node, scoped_nodes.Function):
+            return True
+    return False
+
+
 
 class DocstringChecker(PylintDocStringChecker):
     """
@@ -89,7 +115,7 @@ def _check_docstring(self, node_type, node):
         if docstring is None:
             # The node does not have a docstring.
             # But do not check things inside a function or method.
-            if type(node.parent) != scoped_nodes.Function:
+            if not _isInner(node):
                 self.add_message('W9208', node=node)
             return
         elif not docstring.strip():

twistedchecker/functionaltests/docstring_pass.py

@@ -1,4 +1,5 @@
-# enable: W9201,W9202,W9203,W9204,W9205,W9206,W9207
+# enable: W9201,W9202,W9203,W9204,W9205,W9206,W9207,W9208,W9209
+# -*- test-case-name: twistedchecker.test.test_functionaltests.FunctionalTests.test_twistedchecker_functionaltests_docstring_pass -*-
 """
 A docstring with a wrong indentation.
 Docstring should have consistent indentations.
@@ -65,7 +66,7 @@ def f(self):
 
 
 
-class Bar(self):
+class Bar(object):
     """
     A cvar is recognized as being the start of epytext markup.
 
@@ -89,10 +90,22 @@ def b(self):
         @raise BarException: Another exception.
         @returns: C{int}
         """
+        def callback(result):
+            pass
+
+
+
 
+def topLevel():
+    """
+    A top-level function.
+    """
+    class Inner(object):
+        def innerInner(self):
+            pass
 
 
-class Baz(self):
+class Baz(object):
     """
     An ivar is recognized as being the start of epytext markup.