From b96fb9df2926492b08a28fc5a0ad3c8f80095ad8 Mon Sep 17 00:00:00 2001
From: Amir Rachum <amir@rachum.com>
Date: Sat, 23 Apr 2016 12:50:47 +0300
Subject: [PATCH 1/2] Added D404: First word of a docstring should not be
 `This`

---
 src/pydocstyle.py                        | 22 +++++++++++++++++++---
 src/tests/test_cases/unicode_literals.py |  2 +-
 src/tests/test_decorators.py             |  2 +-
 src/tests/test_definitions.py            |  6 +++---
 4 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/src/pydocstyle.py b/src/pydocstyle.py
index 353379a0..e9f4878a 100644
--- a/src/pydocstyle.py
+++ b/src/pydocstyle.py
@@ -703,6 +703,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):
@@ -711,8 +713,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'])
 })
 
 
@@ -1435,7 +1439,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]))
@@ -1684,6 +1687,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):
diff --git a/src/tests/test_cases/unicode_literals.py b/src/tests/test_cases/unicode_literals.py
index 0cc93014..5f7dd700 100644
--- a/src/tests/test_cases/unicode_literals.py
+++ b/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
diff --git a/src/tests/test_decorators.py b/src/tests/test_decorators.py
index 59a1f2a5..4f7a545a 100644
--- a/src/tests/test_decorators.py
+++ b/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):
diff --git a/src/tests/test_definitions.py b/src/tests/test_definitions.py
index b14d1142..bfe6d79b 100644
--- a/src/tests/test_definitions.py
+++ b/src/tests/test_definitions.py
@@ -253,8 +253,8 @@ def test_token_stream():
     assert stream.line == 1
 
 
-def test_pep257():
-    """Run domain-specific tests from test.py file."""
+def test_example_files():
+    """Run domain-specific tests from test case files."""
     test_cases = (
         'test',
         'unicode_literals',
@@ -275,4 +275,4 @@ def test_pep257():
         for error in results:
             assert isinstance(error, Error)
         results = set([(e.definition.name, e.message) for e in results])
-        assert case_module.expectation.expected == results
+        assert case_module.expectation.expected == results, test_case

From e00dc318effb6e57d984723f4a70f68d774e1690 Mon Sep 17 00:00:00 2001
From: Amir Rachum <amir@rachum.com>
Date: Sat, 23 Apr 2016 22:49:35 +0300
Subject: [PATCH 2/2] Updated documentation, included D404 in our self-test.

---
 docs/error_codes.rst   | 2 +-
 docs/release_notes.rst | 7 +++++++
 tox.ini                | 1 +
 3 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/error_codes.rst b/docs/error_codes.rst
index b7bc2eba..85919758 100644
--- a/docs/error_codes.rst
+++ b/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.
diff --git a/docs/release_notes.rst b/docs/release_notes.rst
index fdf94200..987db1be 100644
--- a/docs/release_notes.rst
+++ b/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).
 
diff --git a/tox.ini b/tox.ini
index 2669da31..e375ebd1 100644
--- a/tox.ini
+++ b/tox.ini
@@ -28,3 +28,4 @@ addopts = -rw
 [pep257]
 inherit = false
 convention = pep257
+add-select = D404