Support @property + @abstractmethod without a Returns: section (#261)

Co-authored-by: jsh9 <[email protected]>

Author: barometz

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change Log
 
+## [0.7.5] - 2025-10-25
+
+- Fixed
+  - Fixed the logic to statically detect whether a method is a property or an
+    abstract method
+- Full diff
+  - https://github.com/jsh9/pydoclint/compare/0.7.4...0.7.5
+
 ## [0.7.4] - 2025-10-24
 
 - Added

docs/violation_codes.md

@@ -59,8 +59,8 @@ Other potential causes to `DOC103` include:
 | `DOC202` | Function/method has a return section in docstring, but there are no return statements or annotations |
 | `DOC203` | Return type(s) in the docstring not consistent with the return annotation                            |
 
-Note on `DOC201`: Methods with `@property` as its last decorator do not need to
-have a return section.
+Note on `DOC201`: Methods with `@property` as its outer-most decorator (i.e.,
+on the top) do not need to have a return section.
 
 ## 3. `DOC3xx`: Violations about class docstring and class constructor
 

pydoclint/utils/special_methods.py

@@ -21,12 +21,6 @@ def checkMethodContainsSpecifiedDecorator(
     return (
         isinstance(node.decorator_list, list)
         and len(node.decorator_list) > 0
-        and any(
-            (  # noqa: PAR001
-                isinstance(_, ast.Name)
-                and hasattr(node.decorator_list[-1], 'id')
-                and _.id == decorator
-            )
-            for _ in node.decorator_list
-        )
+        # Only the outermost (0th element) decorator counts
+        and ast.unparse(node.decorator_list[0]) == decorator
     )

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pydoclint"
-version = "0.7.4"
+version = "0.7.5"
 description = "A Python docstring linter that checks arguments, returns, yields, and raises sections"
 readme = "README.md"
 license = {text = "MIT"}

tests/test_data/common/property_method.py

@@ -10,3 +10,43 @@ def something(self) -> float:
         is a "property method" and is intended to be used as an attribute.
         """
         return self.data
+
+class MyOtherClass:
+    def __init__(self):
+        pass
+
+    @property
+    @something
+    @something_else
+    @well
+    def method_1(self) -> float:
+        """
+        Some abstract property.
+
+        This is also OK. When @property is the outer-most decorator (i.e., at
+        the top), the method is still considered a "property method" and thus 
+        does not need a return section.
+        """
+        pass
+
+    @something
+    @property
+    @something_else
+    @well
+    def method_2(self) -> float:
+        """
+        This is NOT a property method, because @property is not the outer-most
+        decorator. Therefore, this method should have a return section.
+        """
+        pass
+
+    @something
+    @something_else
+    @well
+    @property
+    def method_3(self) -> float:
+        """
+        This is NOT a property method, because @property is not the outer-most
+        decorator. Therefore, this method should have a return section.
+        """
+        pass

tests/test_data/google/abstract_method/cases.py

@@ -6,6 +6,8 @@ class AbstractClass(ABC):
     """Example abstract class."""
 
     @abstractmethod
+    @something
+    @something_else
     def abstract_method(self, var1: str) -> Generator[str, None, None]:
         """Abstract method.
 
@@ -22,6 +24,8 @@ def abstract_method(self, var1: str) -> Generator[str, None, None]:
         """
 
     @abstractmethod
+    @hello
+    @world
     def another_abstract_method(self, var1: str) -> Iterator[str]:
         """Another abstract method.
 
@@ -41,6 +45,8 @@ def another_abstract_method(self, var1: str) -> Iterator[str]:
         """
 
     @abstractmethod
+    @good
+    @morning
     def third_abstract_method(self, var1: str) -> str:
         """The 3rd abstract method.
 

tests/test_main.py

@@ -1241,7 +1241,19 @@ def testNoReturnSectionInPropertyMethod(style: str) -> None:
         skipCheckingShortDocstrings=False,
         checkClassAttributes=False,
     )
-    assert len(violations) == 0
+    expected = [
+        'DOC201: Method `MyOtherClass.method_2` does not have a return section in '
+        'docstring',
+        'DOC203: Method `MyOtherClass.method_2` return type(s) in docstring not '
+        'consistent with the return annotation. Return annotation has 1 type(s); '
+        'docstring return section has 0 type(s).',
+        'DOC201: Method `MyOtherClass.method_3` does not have a return section in '
+        'docstring',
+        'DOC203: Method `MyOtherClass.method_3` return type(s) in docstring not '
+        'consistent with the return annotation. Return annotation has 1 type(s); '
+        'docstring return section has 0 type(s).',
+    ]
+    assert list(map(str, violations)) == expected
 
 
 @pytest.mark.parametrize(

tests/utils/test_special_methods.py

@@ -39,6 +39,7 @@ def method1(self):
 
 class A:
     @hello_world
+    @morning
     def method1(self):
         pass
 """
@@ -49,8 +50,9 @@ def method1(self):
     [
         (src1, 'something', False),
         (src2, 'property', True),
-        (src3, 'property', True),
+        (src3, 'property', False),  # because `@property` is not outermost
         (src4, 'hello_world', True),
+        (src4, 'morning', False),  # because `@morning` isn't outermost
         (src4, 'property', False),
     ],
 )