Repository: cupy/cupy

Issue:
Wrong documentation for matmul
Hi,

The documentation for the [matmul](https://docs.cupy.dev/en/v9.0.0/reference/generated/cupy.matmul.html) function is broken since v9.

It should read "Returns the matrix product for two arrays..." like in [v8](https://docs.cupy.dev/en/v8.6.0/reference/generated/cupy.matmul.html), but instead it shows the documentation for the[ _GUFunc class](https://github.com/cupy/cupy/blob/4469fae998df33c72ff40ef954cb08b8f0004b18/cupy/_core/_gufuncs.py#L143).

I assume the docs generation script messed up because matmul is created [using this class](https://github.com/cupy/cupy/blob/4469fae998df33c72ff40ef954cb08b8f0004b18/cupy/linalg/_product.py#L12). 

Cheers.


Discussion:

Resolving patch:
diff --git a/cupy/_core/__init__.py b/cupy/_core/__init__.py
--- a/cupy/_core/__init__.py
+++ b/cupy/_core/__init__.py
@@ -25,7 +25,7 @@
 from cupy._core._routines_linalg import _mat_ptrs  # NOQA
 from cupy._core._routines_linalg import dot  # NOQA
 from cupy._core._routines_linalg import get_compute_type  # NOQA
-from cupy._core._routines_linalg import _matmul  # NOQA
+from cupy._core._routines_linalg import matmul  # NOQA
 from cupy._core._routines_linalg import set_compute_type  # NOQA
 from cupy._core._routines_linalg import tensordot_core  # NOQA
 from cupy._core._routines_logic import create_comparison  # NOQA
diff --git a/cupy/_core/_gufuncs.py b/cupy/_core/_gufuncs.py
--- a/cupy/_core/_gufuncs.py
+++ b/cupy/_core/_gufuncs.py
@@ -1,8 +1,9 @@
-import numpy
+import functools
 import re
 
-import cupy
+import numpy
 
+import cupy
 import cupy._core._routines_manipulation as _manipulation
 from cupy._core import internal
 
@@ -208,6 +209,7 @@ def __init__(self, func, signature, **kwargs):
             if not isinstance(output_coredimss, list)
             else len(output_coredimss)
         )
+        functools.update_wrapper(self, func)
 
     def _apply_func_to_inputs(self, dim, sizes, dims, args, outs):
         # Apply function
diff --git a/cupy/linalg/_product.py b/cupy/linalg/_product.py
--- a/cupy/linalg/_product.py
+++ b/cupy/linalg/_product.py
@@ -9,8 +9,37 @@
 
 from cupy.linalg._solve import inv
 
-matmul = _GUFunc(
-    _core._matmul, '(n?,k),(k,m?)->(n?,m?)', supports_batched=True)
+_gu_func_matmul = _GUFunc(
+    _core.matmul, '(n?,k),(k,m?)->(n?,m?)', supports_batched=True)
+
+
+def matmul(x1, x2, out=None, *, axes=None):
+    """Matrix product of two arrays.
+
+    Returns the matrix product of two arrays and is the implementation of
+    the `@` operator introduced in Python 3.5 following PEP465.
+
+    The main difference against cupy.dot are the handling of arrays with more
+    than 2 dimensions. For more information see :func:`numpy.matmul`.
+
+    .. note::
+        The out array as input is currently not supported.
+
+    Args:
+        x1 (cupy.ndarray): The left argument.
+        x2 (cupy.ndarray): The right argument.
+        out (cupy.ndarray, optional): Output array.
+        axes (List of tuples of int, optional):
+            A list of tuples with indices of axes the matrix multiplication
+            should operate on.
+
+    Returns:
+        cupy.ndarray: Output array.
+
+    .. seealso:: :func:`numpy.matmul`
+
+    """
+    return _gu_func_matmul(x1, x2, out=out, axes=axes)
 
 
 def dot(a, b, out=None):


Test patch: