API docs: improve result stream (#1010)

 * 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

@@ -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
 

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
 

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):

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):