documentation

Signed-off-by: nstarman <nstarkman@protonmail.com>

src/overload_numpy/wrapper/func.py

@@ -287,10 +287,15 @@ class ImplementsFunc(ValidatesType):
     """The overloaded :mod:`numpy` function."""
 
     dispatch_on: type
-    """The type dispatched on. See ``Dispatcher``."""
+    """The type dispatched on. See :class:`~overload_numpy.wrapper.dispatch.Dispatcher`."""
 
     func: Callable[..., Any]
-    """The overloading function."""
+    """The overloading function.
+
+    Has signature::
+
+        func(*args, **kwargs)
+    """
 
     # TODO! when py3.10+ add NotImplemented
     types: TypeConstraint | Collection[TypeConstraint]
@@ -300,7 +305,23 @@ class ImplementsFunc(ValidatesType):
     """
 
     # TODO: parametrize return type?
-    def __call__(self, _: type, /, args: tuple[Any, ...], kwargs: Mapping[str, Any]) -> Any:
+    def __call__(self, _: type, /, args: tuple[Any, ...], kwargs: Mapping[str, Any]) -> object:
+        """Evaluate a |numpy| function with given arguments.
+
+        Parameters
+        ----------
+        calling_type : type, positional-only
+            The calling type of the class for which this is the override.
+        args : tuple[Any, ...]
+            Tuple of arguments to pass to the override.
+        kwargs : Mapping[str, Any]
+            Mapping of keyword arguments to pass to the override.
+
+        Returns
+        -------
+        object
+            The result of evaluating the |numpy| function method.
+        """
         return self.func(*args, **kwargs)
 
 
@@ -357,10 +378,18 @@ class AssistsFunc(ValidatesType):
     """The overloaded :mod:`numpy` function."""
 
     dispatch_on: type
-    """The type dispatched on. See ``Dispatcher``."""
+    """The type dispatched on.
+
+    See :class:`~overload_numpy.wrapper.dispatch.Dispatcher`.
+    """
 
     func: Callable[..., Any]
-    """The overloading function."""
+    """The overloading function.
+
+    Has signature::
+
+        func(calling_type: type, numpy_func: FunctionType, *args, **kwargs)
+    """
 
     # TODO! when py3.10+ add NotImplemented
     types: TypeConstraint | Collection[TypeConstraint]
@@ -371,6 +400,22 @@ class AssistsFunc(ValidatesType):
 
     # TODO: parametrize return type?
     def __call__(self, calling_type: type, /, args: tuple[Any, ...], kwargs: Mapping[str, Any]) -> Any:
+        """Evaluate a |numpy| function with given arguments.
+
+        Parameters
+        ----------
+        calling_type : type, positional-only
+            The calling type of the class for which this is the override.
+        args : tuple[Any, ...]
+            Tuple of arguments to pass to the override.
+        kwargs : Mapping[str, Any]
+            Mapping of keyword arguments to pass to the override.
+
+        Returns
+        -------
+        object
+            The result of evaluating the |numpy| function method.
+        """
         return self.func(calling_type, self.implements, *args, **kwargs)
 
 

src/overload_numpy/wrapper/ufunc.py

@@ -53,11 +53,11 @@ class OverrideUFuncBase:
 
     Parameters
     ----------
-    funcs : dict[str, Callable]
+    funcs : dict[str, Callable], keyword-only
         The overloading function for each |ufunc| method.
-    implements: |ufunc|
+    implements: |ufunc|, keyword-only
         The overloaded |ufunc|.
-    dispatch_on : type
+    dispatch_on : type, keyword-only
         The type dispatched on. See
         `~overload_numpy.wrapper.dispatch.Dispatcher`.
     """
@@ -149,11 +149,14 @@ def register(self, methods: UFMsT) -> RegisterUFuncMethodDecorator:
 class RegisterUFuncMethodDecorator:
     """Decorator to register a |ufunc| method implementation.
 
-    Called by ``OverrideUfuncBase.register``.
+    Called by `~overload_numpy.wrapper.ufunc.OverrideUfuncBase.register`.
     """
 
     funcs_dict: UFuncMethodOverloadMap
+    """dict of the |ufunc| method overloads."""
+
     applicable_methods: set[UFMT]
+    """|ufunc| methods for which this decorator will register overrides."""
 
     def __call__(self, func: C, /) -> C:
         """Decorator to register an overload funcction for |ufunc| methods.
@@ -200,9 +203,19 @@ class OverloadUFuncDecoratorBase(Generic[UT]):
     OverrideCls: ClassVar[type]
 
     dispatch_on: type
+    """The type dispatched on.
+
+    See :class:`~overload_numpy.wrapper.dispatch.Dispatcher`.
+    """
+
     numpy_func: UFuncLike
+    """The :mod:`numpy` function that is being overloaded."""
+
     methods: set[UFMT]
+    """Set of names of |ufunc| methods."""
+
     overloader: NumPyOverloader
+    """|NumPyOverloader| instance."""
 
     def __post_init__(self) -> None:
         # Make single-dispatcher for numpy function
@@ -252,18 +265,38 @@ class ImplementsUFunc(OverrideUFuncBase):
 
     Parameters
     ----------
-    funcs : dict[str, Callable]
+    funcs : dict[str, Callable], keyword-only
         The overloading function for each |ufunc| method, including ``__call__``.
-    implements: |ufunc|
+    implements: |ufunc|, keyword-only
         The overloaded |ufunc|.
-    dispatch_on : type
+    dispatch_on : type, keyword-only
         The type dispatched on. See
         `~overload_numpy.wrapper.dispatch.Dispatcher`.
     """
 
     def __call__(
         self, method: UFMT, _: type, /, args: tuple[Any, ...], kwargs: Mapping[str, Any]
     ) -> object:  # TODO: parametrize return type?
+        """Evaluate a |ufunc| method with given arguments.
+
+        Parameters
+        ----------
+        method : str, positional-only
+            The |ufunc| method to evaluate. One of {'__call__', 'at',
+            'accumulate', 'outer', 'reduce'}. This is validated with
+            `~overload_numpy.wrapper.ufunc.validate_method`.
+        calling_type : type, positional-only
+            The calling type of the class for which this is the override.
+        args : tuple[Any, ...]
+            Tuple of arguments to pass to the override.
+        kwargs : Mapping[str, Any]
+            Mapping of keyword arguments to pass to the override.
+
+        Returns
+        -------
+        object
+            The result of evaluating the |ufunc| method.
+        """
         if not self.validate_method(method):
             return NotImplemented
         return self.funcs[method](*args, **kwargs)
@@ -300,22 +333,58 @@ class AssistsUFunc(OverrideUFuncBase):
 
     Parameters
     ----------
-    funcs : dict[str, Callable]
+    funcs : dict[str, Callable], keyword-only
         The overloading function for each |ufunc| method.
-    implements: |ufunc|
+    implements: |ufunc|, keyword-only
         The overloaded |ufunc|.
-    dispatch_on : type
+    dispatch_on : type, keyword-only
         The type dispatched on. See
         `~overload_numpy.wrapper.dispatch.Dispatcher`.
     """
 
     # TODO: parametrize return type?
     def __call__(self, method: UFMT, calling_type: type, /, args: tuple[Any, ...], kwargs: Mapping[str, Any]) -> object:
+        """Evaluate a |ufunc| method with given arguments.
+
+        Parameters
+        ----------
+        method : str, positional-only
+            The |ufunc| method to evaluate. One of {'__call__', 'at',
+            'accumulate', 'outer', 'reduce'}. This is validated with
+            `~overload_numpy.wrapper.ufunc.validate_method`.
+        calling_type : type, positional-only
+            The calling type of the class for which this is the override.
+        args : tuple[Any, ...]
+            Tuple of arguments to pass to the override.
+        kwargs : Mapping[str, Any]
+            Mapping of keyword arguments to pass to the override.
+
+        Returns
+        -------
+        object
+            The result of evaluating the |ufunc| method.
+        """
         if not self.validate_method(method):
             return NotImplemented
         return self.funcs[method](calling_type, getattr(self.implements, method), *args, **kwargs)
 
 
 @dataclass(frozen=True)
 class AssistsUFuncDecorator(OverloadUFuncDecoratorBase[AssistsUFunc]):
+    """Decorator to register a |ufunc| override assist with |NumPyOverloader|.
+
+    Parameters
+    ----------
+    overloader : |NumPyOverloader|, keyword-only
+        Overloader instance.
+    numpy_func : Callable[..., Any], keyword-only
+        The :mod:`numpy` function that is being overloaded.
+    methods : set[str], keyword-only
+        Set of names of |ufunc| methods -- {'__call__', 'at', 'accumulate',
+        'outer', 'reduce'}.
+    dispatch_on : type, keyword-only
+        The class type for which the overload implementation is being
+        registered.
+    """
+
     OverrideCls: ClassVar[type[AssistsUFunc]] = AssistsUFunc