Don't report DOC6xx if no docstring or short docstring (#145)

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

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

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(

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)

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'

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'

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'

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 '