chore(common): expose yields as a property.

.github/dependabot.yml

@@ -0,0 +1,30 @@
+version: 2
+updates:
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+      time: "11:30"
+      timezone: "UTC"
+    target-branch: main
+    reviewers:
+      - ExpediaGroup/openworld-committers
+    labels:
+      - Dependabot
+
+  # Maintain dependencies for pip
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: daily
+      time: "13:45"
+      timezone: "UTC"
+    open-pull-requests-limit: 10
+    target-branch: main
+    reviewers:
+      - ExpediaGroup/openworld-committers
+    labels:
+      - Dependabot
+    commit-message:
+      prefix: "update "

docstring_parser/common.py

@@ -193,6 +193,17 @@ def many_returns(self) -> T.List[DocstringReturns]:
             item for item in self.meta if isinstance(item, DocstringReturns)
         ]
 
+    @property
+    def yields(self):
+        """Return a single information on function yield.
+
+        Takes the first generator information.
+        """
+        for item in self.meta:
+            if isinstance(item, DocstringReturns) and item.is_generator:
+                return item
+        return None
+
     @property
     def deprecation(self) -> T.Optional[DocstringDeprecated]:
         """Return a single information on function deprecation notes."""

docstring_parser/tests/test_google.py

@@ -598,6 +598,113 @@ def test_returns() -> None:
     assert docstring.many_returns[0] == docstring.returns
 
 
+def test_yields() -> None:
+    """Test parsing returns."""
+    docstring = parse(
+        """
+        Short description
+        """
+    )
+    assert docstring.yields is None
+
+    docstring = parse(
+        """
+        Returns:
+            int: description
+        """
+    )
+    assert docstring.yields is None
+
+    docstring = parse(
+        """
+        Short description
+        Yields:
+            description
+        """
+    )
+    assert docstring.yields is not None
+    assert docstring.yields.type_name is None
+    assert docstring.yields.description == "description"
+    assert docstring.yields.is_generator is True
+
+    docstring = parse(
+        """
+        Short description
+        Yields:
+            description with: a colon!
+        """
+    )
+    assert docstring.yields is not None
+    assert docstring.yields.type_name is None
+    assert docstring.yields.description == "description with: a colon!"
+    assert docstring.yields.is_generator is True
+
+    docstring = parse(
+        """
+        Short description
+        Yields:
+            int: description
+        """
+    )
+    assert docstring.yields is not None
+    assert docstring.yields.type_name == "int"
+    assert docstring.yields.description == "description"
+    assert docstring.yields.is_generator is True
+
+    docstring = parse(
+        """
+        Yields:
+            Optional[Mapping[str, List[int]]]: A description: with a colon
+        """
+    )
+    assert docstring.yields is not None
+    assert docstring.yields.type_name == "Optional[Mapping[str, List[int]]]"
+    assert docstring.yields.description == "A description: with a colon"
+    assert docstring.yields.is_generator is True
+
+    docstring = parse(
+        """
+        Short description
+        Yields:
+            int: description
+            with much text
+
+            even some spacing
+        """
+    )
+    assert docstring.yields is not None
+    assert docstring.yields.type_name == "int"
+    assert docstring.yields.description == (
+        "description\nwith much text\n\neven some spacing"
+    )
+    assert docstring.returns.is_generator is True
+
+    docstring = parse(
+        """
+        Returns:
+            int: description with return first
+
+        Yields:
+            Optional[Mapping[str, List[int]]]: A description: with a colon
+        """
+    )
+    assert docstring.returns is not None
+    assert docstring.yields is not None
+    assert docstring.yields.type_name != docstring.returns.type_name
+
+    docstring = parse(
+        """
+        Yields:
+            Optional[Mapping[str, List[int]]]: A description: with a colon
+
+        Returns:
+            int: description with return last
+        """
+    )
+    assert docstring.returns is not None
+    assert docstring.yields is not None
+    assert docstring.yields.type_name == docstring.returns.type_name
+
 def test_raises() -> None:
     """Test parsing raises."""
     docstring = parse(

requirements.txt

@@ -0,0 +1 @@
+pydoctor~=22.3.0