Backport docstring clarifications for fromfunction, fromstring and correlate

dpnp/dpnp_iface_arraycreation.py

@@ -1921,22 +1921,26 @@ def fromfunction(
     """
     Construct an array by executing a function over each coordinate.
 
-    The resulting array therefore has a value ``fn(x, y, z)`` at
-    coordinate ``(x, y, z)``.
+    The function is called once with one coordinate array for each dimension
+    of `shape` instead of once per coordinate.
+
+    For functions that operate elementwise on array arguments, the resulting
+    array has a value ``fn(x, y, z)`` at coordinate ``(x, y, z)``.
 
     For full documentation refer to :obj:`numpy.fromfunction`.
 
     Parameters
     ----------
     function : callable
-        The function is called with N parameters, where N is the rank of
-        `shape`. Each parameter represents the coordinates of the array varying
+        The function is called once with N coordinate arrays as parameters,
+        where N is the length of `shape`. Each array represents the coordinates
         along a specific axis. For example, if `shape` were ``(2, 2)``, then
         the parameters would be ``array([[0, 0], [1, 1]])`` and
         ``array([[0, 1], [0, 1]])``.
     shape : (N,) tuple of ints
-        Shape of the output array, which also determines the shape of
-        the coordinate arrays passed to `function`.
+        Shape of the coordinate arrays passed to `function`. The shape of the
+        output is determined by the value returned by `function` and may be
+        different from `shape`.
     dtype : {None, str, dtype object}, optional
         Data-type of the coordinate arrays passed to `function`.
         If ``None``, uses a default floating point data type for the device on
@@ -1981,6 +1985,12 @@ def fromfunction(
     This uses :obj:`numpy.fromfunction` and coerces the result to a DPNP array.
     Keywords other than `dtype` and `like` are passed to `function`.
 
+    .. warning::
+        `shape` determines the shape of the coordinate arrays passed to
+        `function`. It does not enforce that the function returns a result
+        with that shape. If `function` returns a scalar, the result is
+        a zero-dimensional array rather than an array with the given `shape`.
+
     See also
     --------
     :obj:`dpnp.indices` : Return an array representing the indices of a grid.
@@ -2153,7 +2163,6 @@ def fromstring(
         A string containing the data.
     dtype : {None, str, dtype object}, optional
         The data type of the array.
-        For binary input data, the data must be in exactly this format.
         If ``None``, uses a default floating point data type for the device on
         which the returned array is allocated.
 
@@ -2165,7 +2174,7 @@ def fromstring(
         Default: ``-1``.
     sep : str
         The string separating numbers in the data; extra whitespace between
-        elements is also ignored.
+        elements is also ignored. This cannot be an empty string.
     device : {None, string, SyclDevice, SyclQueue, Device}, optional
         An array API concept of device where the output array is created.
         `device` can be ``None``, a oneAPI filter selector string, an instance

dpnp/dpnp_iface_statistics.py

@@ -770,6 +770,20 @@ def correlate(a, v, mode="valid", method="auto"):
     .. math:: c'_k = \sum_n a_{n} \cdot \overline{v_{n+k}}
 
     which is related to :math:`c_k` by :math:`c'_k = c_{-k}`.
+    For example:
+
+    >>> import dpnp as np
+    >>> a = np.array([1, 1])
+    >>> v = np.array([1, 2, 3, 4, 5, 6])
+    >>> np.correlate(a, v, "valid")
+    array([11,  9,  7,  5,  3])
+
+    Using DPNP's definition, the valid correlation values correspond to
+    the lags -4, -3, -2, -1, and 0, so the returned values correspond to
+    :math:`[c_{-4}, c_{-3}, c_{-2}, c_{-1}, c_0]`.
+
+    Under the alternative definition, :math:`c'_k = c_{-k}`, the same
+    correlation values are associated with the opposite lag sign.
 
     References
     ----------
@@ -791,7 +805,7 @@ def correlate(a, v, mode="valid", method="auto"):
     array([3.5], dtype=float32)
     >>> np.correlate(a, v, "same")
     array([2. , 3.5, 3. ], dtype=float32)
-    >>> np.correlate([a, v, "full")
+    >>> np.correlate(a, v, "full")
     array([0.5, 2. , 3.5, 3. , 0. ], dtype=float32)
 
     Using complex sequences: