[pydoclint] Add docstring-missing-returns amd `docstring-extraneo…

…us-returns` (`DOC201`, `DOC202`) (#12485)

Co-authored-by: Micha Reiser <[email protected]>

crates/ruff_linter/resources/test/fixtures/pydoclint/DOC201_google.py

@@ -0,0 +1,73 @@
+# DOC201
+def foo(num: int) -> str:
+    """
+    Do something
+
+    Args:
+        num (int): A number
+    """
+    return 'test'
+
+
+# OK
+def foo(num: int) -> str:
+    """
+    Do something
+
+    Args:
+        num (int): A number
+
+    Returns:
+        str: A string
+    """
+    return 'test'
+
+
+class Bar:
+
+    # OK
+    def foo(self) -> str:
+        """
+        Do something
+
+        Args:
+            num (int): A number
+
+        Returns:
+            str: A string
+        """
+        return 'test'
+
+
+    # DOC201
+    def bar(self) -> str:
+        """
+        Do something
+
+        Args:
+            num (int): A number
+        """
+        return 'test'
+
+
+    # OK
+    @property
+    def baz(self) -> str:
+        """
+        Do something
+
+        Args:
+            num (int): A number
+        """
+        return 'test'
+
+
+# OK
+def test():
+    """Do something."""
+    # DOC201
+    def nested():
+        """Do something nested."""
+        return 5
+
+    print("I never return")

crates/ruff_linter/resources/test/fixtures/pydoclint/DOC201_numpy.py

@@ -0,0 +1,76 @@
+# DOC201
+def foo(num: int) -> str:
+    """
+    Do something
+
+    Parameters
+    ----------
+    num : int
+        A number
+    """
+    return 'test'
+
+
+# OK
+def foo(num: int) -> str:
+    """
+    Do something
+
+    Parameters
+    ----------
+    num : int
+        A number
+
+    Returns
+    -------
+    str
+        A string
+    """
+    return 'test'
+
+
+class Bar:
+
+    # OK
+    def foo(self) -> str:
+        """
+        Do something
+
+        Parameters
+        ----------
+        num : int
+            A number
+
+        Returns
+        -------
+        str
+            A string
+        """
+        return 'test'
+
+
+    # DOC201
+    def bar(self) -> str:
+        """
+        Do something
+
+        Parameters
+        ----------
+        num : int
+            A number
+        """
+        return 'test'
+
+
+    # OK
+    @property
+    def baz(self) -> str:
+        """
+        Do something
+
+        Parameters
+        ----------
+        num : int
+            A number
+        """
+        return 'test'

crates/ruff_linter/resources/test/fixtures/pydoclint/DOC202_google.py

@@ -0,0 +1,50 @@
+# OK
+def foo(num: int) -> str:
+    """
+    Do something
+
+    Args:
+        num (int): A number
+    """
+    print('test')
+
+
+# DOC202
+def foo(num: int) -> str:
+    """
+    Do something
+
+    Args:
+        num (int): A number
+
+    Returns:
+        str: A string
+    """
+    print('test')
+
+
+class Bar:
+
+    # DOC202
+    def foo(self) -> str:
+        """
+        Do something
+
+        Args:
+            num (int): A number
+
+        Returns:
+            str: A string
+        """
+        print('test')
+
+
+    # OK
+    def bar(self) -> str:
+        """
+        Do something
+
+        Args:
+            num (int): A number
+        """
+        print('test')

crates/ruff_linter/resources/test/fixtures/pydoclint/DOC202_numpy.py

@@ -0,0 +1,62 @@
+# OK
+def foo(num: int) -> str:
+    """
+    Do something
+
+    Parameters
+    ----------
+    num : int
+        A number
+    """
+    print('test')
+
+
+# DOC202
+def foo(num: int) -> str:
+    """
+    Do something
+
+    Parameters
+    ----------
+    num : int
+        A number
+
+    Returns
+    -------
+    str
+        A string
+    """
+    print('test')
+
+
+class Bar:
+
+    # DOC202
+    def foo(self) -> str:
+        """
+        Do something
+
+        Parameters
+        ----------
+        num : int
+            A number
+
+        Returns
+        -------
+        str
+            A string
+        """
+        print('test')
+
+
+    # OK
+    def bar(self) -> str:
+        """
+        Do something
+
+        Parameters
+        ----------
+        num : int
+            A number
+        """
+        print('test')

crates/ruff_linter/src/checkers/ast/analyze/definitions.rs

@@ -84,6 +84,8 @@ pub(crate) fn definitions(checker: &mut Checker) {
         Rule::UndocumentedPublicPackage,
     ]);
     let enforce_pydoclint = checker.any_enabled(&[
+        Rule::DocstringMissingReturns,
+        Rule::DocstringExtraneousReturns,
         Rule::DocstringMissingException,
         Rule::DocstringExtraneousException,
     ]);

crates/ruff_linter/src/codes.rs

@@ -917,6 +917,8 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
         (FastApi, "002") => (RuleGroup::Preview, rules::fastapi::rules::FastApiNonAnnotatedDependency),
 
         // pydoclint
+        (Pydoclint, "201") => (RuleGroup::Preview, rules::pydoclint::rules::DocstringMissingReturns),
+        (Pydoclint, "202") => (RuleGroup::Preview, rules::pydoclint::rules::DocstringExtraneousReturns),
         (Pydoclint, "501") => (RuleGroup::Preview, rules::pydoclint::rules::DocstringMissingException),
         (Pydoclint, "502") => (RuleGroup::Preview, rules::pydoclint::rules::DocstringExtraneousException),
 

crates/ruff_linter/src/rules/pydoclint/mod.rs

@@ -26,6 +26,8 @@ mod tests {
         Ok(())
     }
 
+    #[test_case(Rule::DocstringMissingReturns, Path::new("DOC201_google.py"))]
+    #[test_case(Rule::DocstringExtraneousReturns, Path::new("DOC202_google.py"))]
     #[test_case(Rule::DocstringMissingException, Path::new("DOC501_google.py"))]
     #[test_case(Rule::DocstringExtraneousException, Path::new("DOC502_google.py"))]
     fn rules_google_style(rule_code: Rule, path: &Path) -> Result<()> {
@@ -45,6 +47,8 @@ mod tests {
         Ok(())
     }
 
+    #[test_case(Rule::DocstringMissingReturns, Path::new("DOC201_numpy.py"))]
+    #[test_case(Rule::DocstringExtraneousReturns, Path::new("DOC202_numpy.py"))]
     #[test_case(Rule::DocstringMissingException, Path::new("DOC501_numpy.py"))]
     #[test_case(Rule::DocstringExtraneousException, Path::new("DOC502_numpy.py"))]
     fn rules_numpy_style(rule_code: Rule, path: &Path) -> Result<()> {