Merge pull request #183 from Nurdok/d404-this

Added D404: First word of the docstring should not be `This`

Author: Nurdok

docs/error_codes.rst

@@ -15,4 +15,4 @@ check only error codes that are part of the `PEP257
 <http://www.python.org/dev/peps/pep-0257/>`_ official convention.
 
 All of the above error codes are checked for by default except for D203,
-D212 and D213.
+D212, D213 and D404.

docs/release_notes.rst

@@ -7,10 +7,17 @@ Release Notes
 Current Development Version
 ---------------------------
 
+New Features
+
 * Added the optional error codes D212 and D213, for checking whether
   the summary of a multi-line docstring starts at the first line,
   respectively at the second line (#174).
 
+* Added D404 - First word of the docstring should not be `This`. It is turned
+  off by default (#183).
+
+Bug Fixes
+
 * The error code D300 is now also being reported if a docstring has
   uppercase literals (``R`` or ``U``) as prefix (#176).
 

src/pydocstyle.py

@@ -699,6 +699,8 @@ def to_rst(cls):
                                  '"signature"')
 D403 = D4xx.create_error('D403', 'First word of the first line should be '
                                  'properly capitalized', '%r, not %r')
+D404 = D4xx.create_error('D404', 'First word of the docstring should not '
+                                 'be `This`')
 
 
 class AttrDict(dict):
@@ -707,8 +709,10 @@ def __getattr__(self, item):
 
 
 conventions = AttrDict({
-    'pep257': set(ErrorRegistry.get_error_codes()) - set(['D203', 'D212',
-                                                          'D213'])
+    'pep257': set(ErrorRegistry.get_error_codes()) - set(['D203',
+                                                          'D212',
+                                                          'D213',
+                                                          'D404'])
 })
 
 
@@ -1431,7 +1435,6 @@ def check_no_blank_before(self, function, docstring):  # def
         There's no blank line either before or after the docstring.
 
         """
-        # NOTE: This does not take into account functions with groups of code.
         if docstring:
             before, _, after = function.source.partition(docstring)
             blanks_before = list(map(is_blank, before.split('\n')[:-1]))
@@ -1680,6 +1683,19 @@ def check_capitalized(self, function, docstring):
             if first_word != first_word.capitalize():
                 return D403(first_word.capitalize(), first_word)
 
+    @check_for(Definition)
+    def check_starts_with_this(self, function, docstring):
+        """D404: First word of the docstring should not be `This`.
+
+        Docstrings should use short, simple language. They should not begin
+        with "This class is [..]" or "This module contains [..]".
+
+        """
+        if docstring:
+            first_word = ast.literal_eval(docstring).split()[0]
+            if first_word.lower() == 'this':
+                return D404()
+
     # Somewhat hard to determine if return value is mentioned.
     # @check(Function)
     def SKIP_check_return_type(self, function, docstring):

src/tests/test_cases/unicode_literals.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""This is a module."""
+"""A module."""
 
 from __future__ import unicode_literals
 from .expected import Expectation

src/tests/test_decorators.py

@@ -13,7 +13,7 @@
 from .. import pydocstyle
 
 
-class TestParser:
+class TestParser(object):
     """Check parsing of Python source code."""
 
     def test_parse_class_single_decorator(self):

tox.ini

@@ -28,3 +28,4 @@ addopts = -rw
 [pep257]
 inherit = false
 convention = pep257
+add-select = D404