feat: Numpy parser: handle return section items with just type, or no name and no type

Issue #173: #173
PR #174: #174
Co-authored-by: Timothée Mazzucotelli <pawamoy@pm.me>

Author: machow

src/griffe/docstrings/numpy.py

@@ -211,7 +211,9 @@ def _read_block(docstring: Docstring, *, offset: int) -> tuple[str, int]:
         |  # or
         (?P<name>{_RE_NAME})\s*:\s*  # just name
         |  # or
-        (?P<type>{_RE_TYPE})\s*  # just type
+        \s*:\s*$  # no name, no type
+        |  # or
+        (?::\s*)?(?P<type>{_RE_TYPE})\s*  # just type
     )
     """,
     re.IGNORECASE | re.VERBOSE,

tests/test_docstrings/helpers.py

@@ -92,5 +92,10 @@ def assert_element_equal(actual: DocstringElement, expected: DocstringElement) -
         actual: The actual element.
         expected: The expected element.
     """
-    assert actual.annotation == expected.annotation
-    assert actual.description == expected.description
+    assert isinstance(actual, type(expected))
+
+    for k in actual.as_dict():
+        src = getattr(actual, k)
+        dst = getattr(expected, k)
+
+        assert src == dst, f"attribute {k!r}, {src!r} != {dst!r}"

tests/test_docstrings/test_numpy.py

@@ -367,6 +367,12 @@ def test_returns_section(parse_numpy: ParserType) -> None:
         flag : bool
             Some kind
             of flag.
+        x :
+            Name only
+        :
+            No name or annotation
+        : int
+            Only annotation
     """
 
     sections, _ = parse_numpy(docstring)
@@ -377,7 +383,22 @@ def test_returns_section(parse_numpy: ParserType) -> None:
     )
     assert_element_equal(
         sections[0].value[1],
-        DocstringReturn(name="", annotation="bool", description="Some kind\nof flag."),
+        DocstringReturn(name="flag", annotation="bool", description="Some kind\nof flag."),
+    )
+
+    assert_element_equal(
+        sections[0].value[2],
+        DocstringReturn(name="x", annotation=None, description="Name only"),
+    )
+
+    assert_element_equal(
+        sections[0].value[3],
+        DocstringReturn(name="", annotation=None, description="No name or annotation"),
+    )
+
+    assert_element_equal(
+        sections[0].value[4],
+        DocstringReturn(name="", annotation="int", description="Only annotation"),
     )
 
 
@@ -405,7 +426,7 @@ def test_yields_section(parse_numpy: ParserType) -> None:
     )
     assert_element_equal(
         sections[0].value[1],
-        DocstringYield(name="", annotation="bool", description="Some kind\nof flag."),
+        DocstringYield(name="flag", annotation="bool", description="Some kind\nof flag."),
     )
 
 
@@ -433,7 +454,7 @@ def test_receives_section(parse_numpy: ParserType) -> None:
     )
     assert_element_equal(
         sections[0].value[1],
-        DocstringReceive(name="", annotation="bool", description="Some kind\nof flag."),
+        DocstringReceive(name="flag", annotation="bool", description="Some kind\nof flag."),
     )