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,7 +260,8 @@ 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
     ----------
@@ -270,11 +271,28 @@ class AsyncIter(AsyncIterator[_T], Awaitable[List[_T]]):  # pylint: disable=dupl
         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:
-        if self._i % self._steps == 0:
+            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]:
@@ -378,6 +416,7 @@ class AsyncIter(AsyncIterator[_T], Awaitable[List[_T]]):  # pylint: disable=dupl
         3
         4
         5
+
         """
         _temp = set()
         async for item in self: