From 4dd16670e3e0d5e0211c4edb6d9e308724e02042 Mon Sep 17 00:00:00 2001 From: jsh9 <25124332+jsh9@users.noreply.github.com> Date: Wed, 26 Jun 2024 15:36:18 -0700 Subject: [PATCH] Don't report DOC6xx if no docstring or short docstring (#145) --- CHANGELOG.md | 9 +++++++ pydoclint/utils/doc.py | 1 + pydoclint/utils/visitor_helper.py | 13 ++++++++++ pydoclint/visitor.py | 1 + tests/data/google/class_attributes/cases.py | 16 +++++++++--- tests/data/numpy/class_attributes/cases.py | 16 +++++++++--- tests/data/sphinx/class_attributes/cases.py | 16 +++++++++--- tests/test_main.py | 28 +++++++++++++-------- 8 files changed, 81 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 86e4eea..a86e3ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,11 @@ - Changed - Pinned to a higher version (0.0.9) of docstring_parser_fork + - Relaxed class attribute checking logic + - When a class has no docstring, no DOC6xx violations will be reported + - When a class has a short docstring (and + `--skip-checking-short-docstrings`) is set to `True`, no DOC6xx + violations will be reported ## [0.5.1] - 2024-06-24 @@ -14,8 +19,12 @@ class def or in docstring - Changed + - Used a dedicated "attribute" section for Sphinx-style docstrings +- Full diff + - https://github.com/jsh9/pydoclint/compare/0.5.0...0.5.1 + ## [0.5.0] - 2024-06-22 - Added diff --git a/pydoclint/utils/doc.py b/pydoclint/utils/doc.py index befe5a6..035de65 100644 --- a/pydoclint/utils/doc.py +++ b/pydoclint/utils/doc.py @@ -48,6 +48,7 @@ def isShortDocstring(self) -> bool: bool(self.parsed.short_description) or bool(self.parsed.long_description) ) + and len(self.parsed.attrs) == 0 and len(self.parsed.params) == 0 and len(self.parsed.raises) == 0 and self.parsed.returns is None diff --git a/pydoclint/utils/visitor_helper.py b/pydoclint/utils/visitor_helper.py index 8128698..15c6dc2 100644 --- a/pydoclint/utils/visitor_helper.py +++ b/pydoclint/utils/visitor_helper.py @@ -35,12 +35,22 @@ def checkClassAttributesAgainstClassDocstring( shouldCheckArgOrder: bool, argTypeHintsInSignature: bool, argTypeHintsInDocstring: bool, + skipCheckingShortDocstrings: bool, ) -> None: """Check class attribute list against the attribute list in docstring""" classAttributes = _collectClassAttributes(node) actualArgs: ArgList = _convertClassAttributesIntoArgList(classAttributes) classDocstring: str = getDocstring(node) + + if classDocstring == '': + # We don't check classes without any docstrings. + # We defer to + # flake8-docstrings (https://github.com/PyCQA/flake8-docstrings) + # or pydocstyle (https://www.pydocstyle.org/en/stable/) + # to determine whether a class needs a docstring. + return + try: doc: Doc = Doc(docstring=classDocstring, style=style) except Exception as excp: @@ -54,6 +64,9 @@ def checkClassAttributesAgainstClassDocstring( ) ) + if skipCheckingShortDocstrings and doc.isShortDocstring: + return + docArgs: ArgList = doc.attrList checkDocArgsLengthAgainstActualArgs( diff --git a/pydoclint/visitor.py b/pydoclint/visitor.py index 1bfc70e..c7494ca 100644 --- a/pydoclint/visitor.py +++ b/pydoclint/visitor.py @@ -97,6 +97,7 @@ def visit_ClassDef(self, node: ast.ClassDef): # noqa: D102 shouldCheckArgOrder=self.checkArgOrder, argTypeHintsInSignature=self.argTypeHintsInSignature, argTypeHintsInDocstring=self.argTypeHintsInDocstring, + skipCheckingShortDocstrings=self.skipCheckingShortDocstrings, ) self.generic_visit(node) diff --git a/tests/data/google/class_attributes/cases.py b/tests/data/google/class_attributes/cases.py index 976be2c..6ec77a6 100644 --- a/tests/data/google/class_attributes/cases.py +++ b/tests/data/google/class_attributes/cases.py @@ -116,8 +116,18 @@ def __int__(self): @dataclass class MyClass5: - """ - This is a class - """ + """This is a dataclass""" morning: str + + +class MyClass6: + hello: int = 2 # should produce no violations because there's no docstring + world: str = 'world' + + +class MyClass7: + """This is a short docstring so there shouldn't be any violations""" + + hello: int = 2 + world: str = 'world' diff --git a/tests/data/numpy/class_attributes/cases.py b/tests/data/numpy/class_attributes/cases.py index 509daec..af08d99 100644 --- a/tests/data/numpy/class_attributes/cases.py +++ b/tests/data/numpy/class_attributes/cases.py @@ -143,8 +143,18 @@ def __int__(self): @dataclass class MyClass5: - """ - This is a class - """ + """This is a dataclass""" morning: str + + +class MyClass6: + hello: int = 2 # should produce no violations because there's no docstring + world: str = 'world' + + +class MyClass7: + """This is a short docstring so there shouldn't be any violations""" + + hello: int = 2 + world: str = 'world' diff --git a/tests/data/sphinx/class_attributes/cases.py b/tests/data/sphinx/class_attributes/cases.py index c760ada..a7592a8 100644 --- a/tests/data/sphinx/class_attributes/cases.py +++ b/tests/data/sphinx/class_attributes/cases.py @@ -133,8 +133,18 @@ def __int__(self): @dataclass class MyClass5: - """ - This is a class - """ + """This is a dataclass""" morning: str + + +class MyClass6: + hello: int = 2 # should produce no violations because there's no docstring + world: str = 'world' + + +class MyClass7: + """This is a short docstring so there shouldn't be any violations""" + + hello: int = 2 + world: str = 'world' diff --git a/tests/test_main.py b/tests/test_main.py index a956e98..dee0421 100644 --- a/tests/test_main.py +++ b/tests/test_main.py @@ -191,6 +191,15 @@ def testClassAttributes( 'class attributes: [arg1: float, indices: int]. (Please read ' 'https://jsh9.github.io/pydoclint/checking_class_attributes.html on how to ' 'correctly document class attributes.)', + 'DOC101: Method `MyClass2.__init__`: Docstring contains fewer arguments than ' + 'in function signature. ', + 'DOC109: Method `MyClass2.__init__`: The option ' + '`--arg-type-hints-in-docstring` is `True` but there are no type hints in the ' + 'docstring arg list ', + 'DOC103: Method `MyClass2.__init__`: Docstring arguments are different from ' + 'function arguments. (Or could be other formatting issues: ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). ' + 'Arguments in the function signature but not in the docstring: [arg1: int].', 'DOC105: Method `MyClass2.do_something`: Argument names match, but type hints ' 'in these args do not match: arg2', 'DOC601: Class `MyClass3`: Class docstring contains fewer class attributes ' @@ -224,22 +233,21 @@ def testClassAttributes( 'str]. (Please read ' 'https://jsh9.github.io/pydoclint/checking_class_attributes.html on how to ' 'correctly document class attributes.)', - 'DOC601: Class `MyClass5`: Class docstring contains fewer class attributes ' - 'than actual class attributes. (Please read ' - 'https://jsh9.github.io/pydoclint/checking_class_attributes.html on how to ' - 'correctly document class attributes.)', - 'DOC603: Class `MyClass5`: Class docstring attributes are different from ' - 'actual class attributes. (Or could be other formatting issues: ' - 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). ' - 'Attributes in the class definition but not in the docstring: [morning: str]. ' - '(Please read https://jsh9.github.io/pydoclint/checking_class_attributes.html ' - 'on how to correctly document class attributes.)', ], False: [ 'DOC105: Method `MyClass1.__init__`: Argument names match, but type hints in ' 'these args do not match: arg1', 'DOC105: Method `MyClass1.do_something`: Argument names match, but type hints ' 'in these args do not match: arg2', + 'DOC101: Method `MyClass2.__init__`: Docstring contains fewer arguments than ' + 'in function signature. ', + 'DOC109: Method `MyClass2.__init__`: The option ' + '`--arg-type-hints-in-docstring` is `True` but there are no type hints in the ' + 'docstring arg list ', + 'DOC103: Method `MyClass2.__init__`: Docstring arguments are different from ' + 'function arguments. (Or could be other formatting issues: ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). ' + 'Arguments in the function signature but not in the docstring: [arg1: int].', 'DOC105: Method `MyClass2.do_something`: Argument names match, but type hints ' 'in these args do not match: arg2', 'DOC102: Method `MyClass3.__init__`: Docstring contains more arguments than '