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 `_ 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/src/pydocstyle.py b/src/pydocstyle.py index 8fbc1fa1..b31fb748 100644 --- a/src/pydocstyle.py +++ b/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): 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/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