Fix sleeping and improve documentation for AsyncIter (#3776)

* welp

Signed-off-by: Drapersniper <27962761+drapersniper@users.noreply.github.com>

* moar docs

Signed-off-by: Drapersniper <27962761+drapersniper@users.noreply.github.com>

* moar docs

Signed-off-by: Drapersniper <27962761+drapersniper@users.noreply.github.com>

* Remove unnecessary items in `:exclude-members:`

* Make whitespace in docstrings consistent

Co-authored-by: jack1142 <6032823+jack1142@users.noreply.github.com>

docs/framework_utils.rst

@@ -12,6 +12,7 @@ General Utility
 
 .. autoclass:: AsyncIter
     :members:
+    :special-members: __await__
     :exclude-members: enumerate, filter
 
     .. automethod:: enumerate

redbot/core/utils/__init__.py

@@ -260,21 +260,39 @@ def bounded_gather(
 
 
 class AsyncIter(AsyncIterator[_T], Awaitable[List[_T]]):  # pylint: disable=duplicate-bases
-    """Asynchronous iterator yielding items from ``iterable`` that sleeps for ``delay`` seconds every ``steps`` items.
+    """Asynchronous iterator yielding items from ``iterable``
+    that sleeps for ``delay`` seconds every ``steps`` items.
 
     Parameters
     ----------
-    iterable : Iterable
+    iterable: Iterable
         The iterable to make async.
     delay: Union[float, int]
         The amount of time in seconds to sleep.
     steps: int
         The number of iterations between sleeps.
+
+    Raises
+    ------
+    ValueError
+        When ``steps`` is lower than 1.
+
+    Examples
+    --------
+    >>> from redbot.core.utils import AsyncIter
+    >>> async for value in AsyncIter(range(3)):
+    ...     print(value)
+    0
+    1
+    2
+
     """
 
     def __init__(
         self, iterable: Iterable[_T], delay: Union[float, int] = 0, steps: int = 1
     ) -> None:
+        if steps < 1:
+            raise ValueError("Steps must be higher than or equals to 1")
         self._delay = delay
         self._iterator = iter(iterable)
         self._i = 0
@@ -288,16 +306,36 @@ class AsyncIter(AsyncIterator[_T], Awaitable[List[_T]]):  # pylint: disable=dupl
             item = next(self._iterator)
         except StopIteration:
             raise StopAsyncIteration
-        self._i += 1
-        if self._i % self._steps == 0:
+        if self._i == self._steps:
+            self._i = 0
             await asyncio.sleep(self._delay)
+        self._i += 1
         return item
 
     def __await__(self) -> Generator[Any, None, List[_T]]:
+        """Returns a list of the iterable.
+
+        Examples
+        --------
+        >>> from redbot.core.utils import AsyncIter
+        >>> iterator = AsyncIter(range(5))
+        >>> await iterator
+        [0, 1, 2, 3, 4]
+
+        """
         return self.flatten().__await__()
 
     async def flatten(self) -> List[_T]:
-        """Returns a list of the iterable."""
+        """Returns a list of the iterable.
+
+        Examples
+        --------
+        >>> from redbot.core.utils import AsyncIter
+        >>> iterator = AsyncIter(range(5))
+        >>> await iterator.flatten()
+        [0, 1, 2, 3, 4]
+
+        """
         return [item async for item in self]
 
     def filter(self, function: Callable[[_T], Union[bool, Awaitable[bool]]]) -> AsyncFilter[_T]:
@@ -306,7 +344,7 @@ class AsyncIter(AsyncIterator[_T], Awaitable[List[_T]]):  # pylint: disable=dupl
 
         Parameters
         ----------
-        function : Callable[[T], Union[bool, Awaitable[bool]]]
+        function: Callable[[T], Union[bool, Awaitable[bool]]]
             A function or coroutine function which takes one item of ``iterable``
             as an argument, and returns ``True`` or ``False``.
 
@@ -342,7 +380,7 @@ class AsyncIter(AsyncIterator[_T], Awaitable[List[_T]]):  # pylint: disable=dupl
 
         Parameters
         ----------
-        start : int
+        start: int
             The index to start from. Defaults to 0.
 
         Returns
@@ -378,6 +416,7 @@ class AsyncIter(AsyncIterator[_T], Awaitable[List[_T]]):  # pylint: disable=dupl
         3
         4
         5
+
         """
         _temp = set()
         async for item in self: