From d3efb4a82fd62a962d0824f51f178d78eecbcbbc Mon Sep 17 00:00:00 2001
From: Robsdedude <rouven.bauer@neo4j.com>
Date: Mon, 8 Jan 2024 12:52:02 +0100
Subject: [PATCH] API docs: improve result stream

 * Show `__aiter__` and `__anext__` methods' docs string and type annotations.
 * Mention `StopAsyncIteration` exception raised by `__atier__`.
 * Same corresponding changes to the sync API.
---
 docs/source/api.rst             | 4 ++--
 docs/source/async_api.rst       | 6 ++----
 src/neo4j/_async/work/result.py | 5 ++++-
 src/neo4j/_sync/work/result.py  | 5 ++++-
 4 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/docs/source/api.rst b/docs/source/api.rst
index df87ca89a..755ac2254 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -1347,9 +1347,9 @@ A :class:`neo4j.Result` is attached to an active connection, through a :class:`n
 
 .. autoclass:: neo4j.Result()
 
-    .. describe:: iter(result)
+    .. automethod:: __iter__
 
-    .. describe:: next(result)
+    .. automethod:: __next__
 
     .. automethod:: keys
 
diff --git a/docs/source/async_api.rst b/docs/source/async_api.rst
index 40e7451e2..0a52240bf 100644
--- a/docs/source/async_api.rst
+++ b/docs/source/async_api.rst
@@ -865,11 +865,9 @@ A :class:`neo4j.AsyncResult` is attached to an active connection, through a :cla
 
 .. autoclass:: neo4j.AsyncResult()
 
-    .. method:: __aiter__()
-        :async:
+    .. automethod:: __aiter__()
 
-    .. method:: __anext__()
-        :async:
+    .. automethod:: __anext__()
 
     .. automethod:: keys
 
diff --git a/src/neo4j/_async/work/result.py b/src/neo4j/_async/work/result.py
index 704bb2bd6..447e7ff65 100644
--- a/src/neo4j/_async/work/result.py
+++ b/src/neo4j/_async/work/result.py
@@ -286,7 +286,10 @@ async def __aiter__(self) -> t.AsyncIterator[Record]:
 
     @AsyncNonConcurrentMethodChecker.non_concurrent_method
     async def __anext__(self) -> Record:
-        """Advance the result stream and return the record."""
+        """Advance the result stream and return the record.
+
+        :raises StopAsyncIteration: if no more records are available.
+        """
         return await self.__aiter__().__anext__()
 
     async def _attach(self):
diff --git a/src/neo4j/_sync/work/result.py b/src/neo4j/_sync/work/result.py
index 632cd8c17..72bfa52a4 100644
--- a/src/neo4j/_sync/work/result.py
+++ b/src/neo4j/_sync/work/result.py
@@ -286,7 +286,10 @@ def __iter__(self) -> t.Iterator[Record]:
 
     @NonConcurrentMethodChecker.non_concurrent_method
     def __next__(self) -> Record:
-        """Advance the result stream and return the record."""
+        """Advance the result stream and return the record.
+
+        :raises StopIteration: if no more records are available.
+        """
         return self.__iter__().__next__()
 
     def _attach(self):