[pydoclint] Permit yielding None in DOC402 and DOC403

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

@@ -187,3 +187,9 @@ def foo(s: str) -> str | None:
         A string.
     """
     return None
+
+
+# DOC201
+def bar() -> int | None:
+    """Bar-y method"""
+    return

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

@@ -87,3 +87,14 @@ def f(num: int):
         num (int): A number
     """
     yield 1
+
+
+from collections import abc
+
+
+# DOC402
+def foo() -> abc.Generator[int | None, None, None]:
+    """
+    Do something
+    """
+    yield

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

@@ -60,3 +60,73 @@ def bar(self) -> str:
             A number
         """
         yield 'test'
+
+
+import typing
+
+
+# OK
+def foo() -> typing.Generator[None, None, None]:
+    """
+    Do something
+    """
+    yield None
+
+
+# OK
+def foo() -> typing.Generator[None, None, None]:
+    """
+    Do something
+    """
+    yield
+
+
+# DOC402
+def foo() -> typing.Generator[int | None, None, None]:
+    """
+    Do something
+    """
+    yield None
+    yield 1
+
+
+# DOC402
+def foo() -> typing.Generator[int, None, None]:
+    """
+    Do something
+    """
+    yield None
+
+
+# OK
+def foo():
+    """
+    Do something
+    """
+    yield None
+
+
+# OK
+def foo():
+    """
+    Do something
+    """
+    yield
+
+
+# DOC402
+def foo():
+    """
+    Do something
+    """
+    yield None
+    yield 1
+
+
+# DOC402
+def foo():
+    """
+    Do something
+    """
+    yield 1
+    yield

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

@@ -48,3 +48,50 @@ def bar(self) -> str:
             num (int): A number
         """
         print('test')
+
+
+import typing
+
+
+# OK
+def foo() -> typing.Generator[None, None, None]:
+    """
+    Do something
+
+    Yields:
+        When X.
+    """
+    yield
+
+
+# OK
+def foo() -> typing.Generator[None, None, None]:
+    """
+    Do something
+
+    Yields:
+        When X.
+    """
+    yield None
+
+
+# OK
+def foo():
+    """
+    Do something
+
+    Yields:
+        When X.
+    """
+    yield
+
+
+# OK
+def foo():
+    """
+    Do something
+
+    Yields:
+        When X.
+    """
+    yield None

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

@@ -60,3 +60,54 @@ def bar(self) -> str:
             A number
         """
         print('test')
+
+
+import typing
+
+
+# OK
+def foo() -> typing.Generator[None, None, None]:
+    """
+    Do something
+
+    Yields
+    ------
+        When X.
+    """
+    yield None
+
+
+# OK
+def foo() -> typing.Generator[None, None, None]:
+    """
+    Do something
+
+    Yields
+    ------
+        When X.
+    """
+    yield
+
+
+# OK
+def foo():
+    """
+    Do something
+
+    Yields
+    ------
+        When X.
+    """
+    yield None
+
+
+# OK
+def foo():
+    """
+    Do something
+
+    Yields
+    ------
+        When X.
+    """
+    yield

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

@@ -3,6 +3,7 @@ use ruff_diagnostics::Diagnostic;
 use ruff_diagnostics::Violation;
 use ruff_macros::{derive_message_formats, violation};
 use ruff_python_ast::helpers::map_callable;
+use ruff_python_ast::helpers::map_subscript;
 use ruff_python_ast::name::QualifiedName;
 use ruff_python_ast::visitor::Visitor;
 use ruff_python_ast::{self as ast, visitor, Expr, Stmt};
@@ -126,7 +127,8 @@ impl Violation for DocstringExtraneousReturns {
 /// Docstrings missing yields sections are a sign of incomplete documentation
 /// or refactors.
 ///
-/// This rule is not enforced for abstract methods and stubs functions.
+/// This rule is not enforced for abstract methods, stubs functions, or
+/// functions that only yield `None`.
 ///
 /// ## Example
 /// ```python
@@ -499,6 +501,7 @@ fn parse_entries_numpy(content: &str) -> Vec<QualifiedName> {
 #[derive(Debug)]
 struct YieldEntry {
     range: TextRange,
+    is_none_yield: bool,
 }
 
 impl Ranged for YieldEntry {
@@ -644,6 +647,12 @@ impl<'a> Visitor<'a> for BodyVisitor<'a> {
                     is_none_return: value.is_none_literal_expr(),
                 });
             }
+            Stmt::Return(ast::StmtReturn { range, value: None }) => {
+                self.returns.push(ReturnEntry {
+                    range: *range,
+                    is_none_return: true,
+                });
+            }
             Stmt::FunctionDef(_) | Stmt::ClassDef(_) => return,
             _ => {}
         }
@@ -655,12 +664,24 @@ impl<'a> Visitor<'a> for BodyVisitor<'a> {
         match expr {
             Expr::Yield(ast::ExprYield {
                 range,
-                value: Some(_),
+                value: Some(value),
             }) => {
-                self.yields.push(YieldEntry { range: *range });
+                self.yields.push(YieldEntry {
+                    range: *range,
+                    is_none_yield: value.is_none_literal_expr(),
+                });
+            }
+            Expr::Yield(ast::ExprYield { range, value: None }) => {
+                self.yields.push(YieldEntry {
+                    range: *range,
+                    is_none_yield: true,
+                });
             }
             Expr::YieldFrom(ast::ExprYieldFrom { range, .. }) => {
-                self.yields.push(YieldEntry { range: *range });
+                self.yields.push(YieldEntry {
+                    range: *range,
+                    is_none_yield: false,
+                });
             }
             Expr::Lambda(_) => return,
             _ => {}
@@ -711,6 +732,28 @@ fn yields_documented(
         || (matches!(convention, Some(Convention::Google)) && starts_with_yields(docstring))
 }
 
+/// Returns the first subscript element of a generator annotation, if it exists.
+fn generator_yield_annotation<'a>(expr: &'a Expr, checker: &'a Checker) -> Option<&'a Expr> {
+    let slice = expr.as_subscript_expr()?.slice.as_tuple_expr()?;
+    if matches!(
+        checker
+            .semantic()
+            .resolve_qualified_name(map_subscript(expr))?
+            .segments(),
+        [
+            "typing" | "typing_extensions",
+            "Generator" | "AsyncGenerator" | "Iterator" | "AsyncIterator"
+        ] | [
+            "collections",
+            "abc",
+            "Generator" | "AsyncGenerator" | "Iterator" | "AsyncIterator"
+        ]
+    ) {
+        return slice.elts.first();
+    }
+    None
+}
+
 /// DOC201, DOC202, DOC402, DOC403, DOC501, DOC502
 pub(crate) fn check_docstring(
     checker: &mut Checker,
@@ -779,8 +822,20 @@ pub(crate) fn check_docstring(
     if checker.enabled(Rule::DocstringMissingYields) {
         if !yields_documented(docstring, &docstring_sections, convention) {
             if let Some(body_yield) = body_entries.yields.first() {
-                let diagnostic = Diagnostic::new(DocstringMissingYields, body_yield.range());
-                diagnostics.push(diagnostic);
+                match function_def.returns.as_deref() {
+                    Some(returns)
+                        if generator_yield_annotation(returns, checker)
+                            .map_or(true, |expr| !Expr::is_none_literal_expr(expr)) =>
+                    {
+                        diagnostics
+                            .push(Diagnostic::new(DocstringMissingYields, body_yield.range()));
+                    }
+                    None if body_entries.yields.iter().any(|entry| !entry.is_none_yield) => {
+                        diagnostics
+                            .push(Diagnostic::new(DocstringMissingYields, body_yield.range()));
+                    }
+                    _ => {}
+                }
             }
         }
     }

crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-returns_DOC201_numpy.py.snap

@@ -58,3 +58,12 @@ DOC201_numpy.py:189:5: DOC201 `return` is not documented in docstring
     |     ^^^^^^^^^^^ DOC201
     |
     = help: Add a "Returns" section to the docstring
+
+DOC201_numpy.py:195:5: DOC201 `return` is not documented in docstring
+    |
+193 | def bar() -> int | None:
+194 |     """Bar-y method"""
+195 |     return
+    |     ^^^^^^ DOC201
+    |
+    = help: Add a "Returns" section to the docstring

crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-yields_DOC402_google.py.snap

@@ -38,3 +38,12 @@ DOC402_google.py:67:5: DOC402 `yield` is not documented in docstring
    |     ^^^^^^^^^^^^^^^^^^^^ DOC402
    |
    = help: Add a "Yields" section to the docstring
+
+DOC402_google.py:100:5: DOC402 `yield` is not documented in docstring
+    |
+ 98 |     Do something
+ 99 |     """
+100 |     yield
+    |     ^^^^^ DOC402
+    |
+    = help: Add a "Yields" section to the docstring

crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-yields_DOC402_numpy.py.snap

@@ -18,3 +18,42 @@ DOC402_numpy.py:62:9: DOC402 `yield` is not documented in docstring
    |         ^^^^^^^^^^^^ DOC402
    |
    = help: Add a "Yields" section to the docstring
+
+DOC402_numpy.py:89:5: DOC402 `yield` is not documented in docstring
+   |
+87 |     Do something
+88 |     """
+89 |     yield None
+   |     ^^^^^^^^^^ DOC402
+90 |     yield 1
+   |
+   = help: Add a "Yields" section to the docstring
+
+DOC402_numpy.py:98:5: DOC402 `yield` is not documented in docstring
+   |
+96 |     Do something
+97 |     """
+98 |     yield None
+   |     ^^^^^^^^^^ DOC402
+   |
+   = help: Add a "Yields" section to the docstring
+
+DOC402_numpy.py:122:5: DOC402 `yield` is not documented in docstring
+    |
+120 |     Do something
+121 |     """
+122 |     yield None
+    |     ^^^^^^^^^^ DOC402
+123 |     yield 1
+    |
+    = help: Add a "Yields" section to the docstring
+
+DOC402_numpy.py:131:5: DOC402 `yield` is not documented in docstring
+    |
+129 |     Do something
+130 |     """
+131 |     yield 1
+    |     ^^^^^^^ DOC402
+132 |     yield
+    |
+    = help: Add a "Yields" section to the docstring