Added D105: missing docstring in magic method

Author: Nurdok

docs/release_notes.rst

@@ -27,7 +27,7 @@ Bug Fixes
 
 
 0.6.0 - July 20th, 2015
----------------------------
+-----------------------
 
 New Features
 

src/pep257.py

@@ -67,14 +67,17 @@ def next(obj, default=nothing):
 NO_VIOLATIONS_RETURN_CODE = 0
 VIOLATIONS_RETURN_CODE = 1
 INVALID_OPTIONS_RETURN_CODE = 2
+VARIADIC_MAGIC_METHODS = ('__init__', '__call__', '__new__')
 
 
 def humanize(string):
     return re(r'(.)([A-Z]+)').sub(r'\1 \2', string).lower()
 
 
 def is_magic(name):
-    return name.startswith('__') and name.endswith('__')
+    return (name.startswith('__') and
+            name.endswith('__') and
+            name not in VARIADIC_MAGIC_METHODS)
 
 
 def is_ascii(string):
@@ -156,8 +159,8 @@ class Function(Definition):
     def is_public(self):
         if self.all is not None:
             return self.name in self.all
-        else:  # TODO: are there any magic functions? not methods
-            return not self.name.startswith('_') or is_magic(self.name)
+        else:
+            return not self.name.startswith('_')
 
 
 class NestedFunction(Function):
@@ -174,7 +177,9 @@ def is_public(self):
             # Given 'foo', match 'foo.bar' but not 'foobar' or 'sfoo'
             if re(r"^{0}\.".format(self.name)).match(decorator.name):
                 return False
-        name_is_public = not self.name.startswith('_') or is_magic(self.name)
+        name_is_public = (not self.name.startswith('_') or
+                          self.name in VARIADIC_MAGIC_METHODS or
+                          is_magic(self.name))
         return self.parent.is_public and name_is_public
 
 
@@ -633,6 +638,7 @@ def to_rst(cls):
 D102 = D1xx.create_error('D102', 'Missing docstring in public method')
 D103 = D1xx.create_error('D103', 'Missing docstring in public function')
 D104 = D1xx.create_error('D104', 'Missing docstring in public package')
+D105 = D1xx.create_error('D105', 'Missing docstring in magic method')
 
 D2xx = ErrorRegistry.create_group('D2', 'Whitespace Issues')
 D200 = D2xx.create_error('D200', 'One-line docstring should fit on one line '
@@ -988,8 +994,9 @@ def check_docstring_missing(self, definition, docstring):
         if (not docstring and definition.is_public or
                 docstring and is_blank(eval(docstring))):
             codes = {Module: D100, Class: D101, NestedClass: D101,
-                     Method: D102, Function: D103, NestedFunction: D103,
-                     Package: D104}
+                     Method: (lambda: D105() if is_magic(definition.name)
+                              else D102()),
+                     Function: D103, NestedFunction: D103, Package: D104}
             return codes[type(definition)]()
 
     @check_for(Definition)

src/tests/test_cases/test.py

@@ -28,6 +28,14 @@ def _ok_since_private():
     def __init__(self=None):
         pass
 
+    @expect('D105: Missing docstring in magic method')
+    def __str__(self=None):
+        pass
+
+    @expect('D102: Missing docstring in public method')
+    def __call__(self=None, x=None, y=None, z=None):
+        pass
+
 
 @expect('D103: Missing docstring in public function')
 def function():