add real docstring to AioretryProtocol

kaioretry/types.py

@@ -1,4 +1,6 @@
-"""Custom types used by kaioretry"""
+"""
+Kaioretry defines a bunch
+"""
 
 
 from typing import TypeAlias, TypeVar, ParamSpec, Any, overload
@@ -30,6 +32,7 @@
 
 
 FuncParam = ParamSpec('FuncParam')
+
 FuncRetVal = TypeVar('FuncRetVal')
 
 Function: TypeAlias = Callable[..., Any]
@@ -47,7 +50,11 @@
 
 class AioretryProtocol(Protocol):
 
-    """The type of the main aioretry decorator"""
+    """The :py:class:`typing.Protocol` describing the behaviour of the
+    :py:func:`~kaioretry.aioretry` decorator.
+
+    .. automethod:: __call__
+    """
 
     @overload
     def __call__(self, func: AwaitableFunc[FuncParam, FuncRetVal]) \
@@ -61,4 +68,14 @@ def __call__(self, func: Callable[FuncParam, FuncRetVal]) \
 
     def __call__(self, func: AnyFunction[FuncParam, FuncRetVal]) \
             -> AioretryCoro[FuncParam, FuncRetVal]:
+        """When called (to decorate a function), an aioretry decorator will...
+
+        :param func: ... take a function as input...
+
+        :returns: and, if ``func`` returns an
+          :py:class:`~collections.abc.Awaitable`, then return a same-signature
+          same-type coroutine function. If ``func`` does not, then return a
+          same-signature *coroutine* function that, once awaited, return
+          ``func`` original return value.
+        """
         ...