[pydoclint] Permit yielding None in DOC402 and DOC403 (#13148)

Co-authored-by: Alex Waygood <alex.waygood@gmail.com>

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

@@ -187,3 +187,50 @@ def foo(s: str) -> str | None:
         A string.
     """
     return None
+
+
+# DOC201
+def bar() -> int | None:
+    """Bar-y method"""
+    return
+
+
+from collections.abc import Iterator, Generator
+
+
+# This is okay -- returning `None` is implied by `Iterator[str]`;
+# no need to document it
+def generator_function() -> Iterator[str]:
+    """Generate some strings"""
+    yield from "abc"
+    return
+
+
+# This is okay -- returning `None` is stated by `Generator[str, None, None]`;
+# no need to document it
+def generator_function_2() -> Generator[str, None, None]:
+    """Generate some strings"""
+    yield from "abc"
+    return
+
+
+# DOC201 -- returns None but `Generator[str, None, int | None]`
+# indicates it could sometimes return `int`
+def generator_function_3() -> Generator[str, None, int | None]:
+    """Generate some strings"""
+    yield from "abc"
+    return
+
+
+# DOC201 -- no type annotation and a non-None return
+# indicates it could sometimes return `int`
+def generator_function_4():
+    """Generate some strings"""
+    yield from "abc"
+    return 42
+
+
+# DOC201 -- no `yield` expressions, so not a generator function
+def not_a_generator() -> Iterator[int]:
+    """"No returns documented here, oh no"""
+    return (x for x in range(42))

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

@@ -73,3 +73,15 @@ def f(self):
             dict: The values
         """
         return
+
+
+# DOC202 -- never explicitly returns anything, just short-circuits
+def foo(s: str, condition: bool):
+    """Fooey things.
+
+    Returns:
+        None
+    """
+    if not condition:
+        return
+    print(s)

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

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

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

@@ -60,3 +60,81 @@ 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
+
+
+# DOC402
+def bar() -> typing.Iterator[int | None]:
+    """
+    Do something
+    """
+    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