Update docstrings for elementwise functions (#2406)

The PR updates docstrings for elementwise functions to have a blank line
prior `Default` value, also to add expected dtype of input arrays where
missing, to align the dtypes with implementation and to fix some typos
which were identified.
Also a description of `include_initial` keyword is aligned for
cumulative functions.

Author: antonwolfy

.github/workflows/check-mkl-interfaces.yaml

@@ -229,7 +229,7 @@ jobs:
           python -c "import dpnp; print(dpnp.__version__)"
 
       - name: Run tests
-        if: env.rerun-tests-on-failure == 'true'
+        if: env.rerun-tests-on-failure != 'true'
         run: |
           python -m pytest -ra --pyargs dpnp.tests
         env:

dpnp/dpnp_iface_bitwise.py

@@ -130,21 +130,17 @@ def binary_repr(num, width=None):
 
 _BITWISE_AND_DOCSTRING = """
 Computes the bitwise AND of the underlying binary representation of each
-element `x1_i` of the input array `x1` with the respective element `x2_i`
-of the input array `x2`.
+element :math:`x1_i` of the input array `x1` with the respective element
+:math:`x2_i` of the input array `x2`.
 
 For full documentation refer to :obj:`numpy.bitwise_and`.
 
 Parameters
 ----------
 x1 : {dpnp.ndarray, usm_ndarray, scalar}
-    First input array, expected to have integer or boolean data type.
-    Both inputs `x1` and `x2` can not be scalars at the same time.
+    First input array, expected to have an integer or boolean data type.
 x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array, also expected to have integer or boolean data
-    type. Both inputs `x1` and `x2` can not be scalars at the same time.
-    If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
-    (which becomes the shape of the output).
+    Second input array, also expected to have an integer or boolean data type.
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -175,6 +171,13 @@ def binary_repr(num, width=None):
 :obj:`dpnp.binary_repr` : Return the binary representation of the input number
                           as a string.
 
+Notes
+-----
+At least one of `x1` or `x2` must be an array.
+
+If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
+(which becomes the shape of the output).
+
 Examples
 --------
 >>> import dpnp as np
@@ -206,6 +209,7 @@ def binary_repr(num, width=None):
 '1100'
 >>> np.bitwise_and(np.array([14, 3]), 13)
 array([12,  1])
+
 """
 
 bitwise_and = DPNPBinaryFunc(
@@ -225,7 +229,7 @@ def binary_repr(num, width=None):
 Parameters
 ----------
 x : {dpnp.ndarray, usm_ndarray}
-    Input array, expected to have integer or boolean data type.
+    Input array, expected to have an integer data type.
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -272,21 +276,17 @@ def binary_repr(num, width=None):
 
 _BITWISE_OR_DOCSTRING = """
 Computes the bitwise OR of the underlying binary representation of each
-element `x1_i` of the input array `x1` with the respective element `x2_i`
-of the input array `x2`.
+element :math:`x1_i` of the input array `x1` with the respective element
+:math:`x2_i` of the input array `x2`.
 
 For full documentation refer to :obj:`numpy.bitwise_or`.
 
 Parameters
 ----------
 x1 : {dpnp.ndarray, usm_ndarray, scalar}
-    First input array, expected to have integer or boolean data type.
-    Both inputs `x1` and `x2` can not be scalars at the same time.
+    First input array, expected to have an integer or boolean data type.
 x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array, also expected to have integer or boolean data
-    type. Both inputs `x1` and `x2` can not be scalars at the same time.
-    If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
-    (which becomes the shape of the output).
+    Second input array, also expected to have an integer or boolean data type.
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -317,6 +317,13 @@ def binary_repr(num, width=None):
 :obj:`dpnp.binary_repr` : Return the binary representation of the input number
                           as a string.
 
+Notes
+-----
+At least one of `x1` or `x2` must be an array.
+
+If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
+(which becomes the shape of the output).
+
 Examples
 --------
 >>> import dpnp as np
@@ -339,6 +346,7 @@ def binary_repr(num, width=None):
 array(29)
 >>> np.binary_repr(29)
 '11101'
+
 """
 
 bitwise_or = DPNPBinaryFunc(
@@ -352,21 +360,17 @@ def binary_repr(num, width=None):
 
 _BITWISE_XOR_DOCSTRING = """
 Computes the bitwise XOR of the underlying binary representation of each
-element `x1_i` of the input array `x1` with the respective element `x2_i`
-of the input array `x2`.
+element :math:`x1_i` of the input array `x1` with the respective element
+:math:`x2_i` of the input array `x2`.
 
 For full documentation refer to :obj:`numpy.bitwise_xor`.
 
 Parameters
 ----------
 x1 : {dpnp.ndarray, usm_ndarray, scalar}
-    First input array, expected to have integer or boolean data type.
-    Both inputs `x1` and `x2` can not be scalars at the same time.
+    First input array, expected to have an integer or boolean data type.
 x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array, also expected to have integer or boolean data
-    type. Both inputs `x1` and `x2` can not be scalars at the same time.
-    If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
-    (which becomes the shape of the output).
+    Second input array, also expected to have an integer or boolean data type.
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -397,6 +401,13 @@ def binary_repr(num, width=None):
 :obj:`dpnp.binary_repr` : Return the binary representation of the input number
                           as a string.
 
+Notes
+-----
+At least one of `x1` or `x2` must be an array.
+
+If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
+(which becomes the shape of the output).
+
 Examples
 --------
 >>> import dpnp as np
@@ -423,6 +434,7 @@ def binary_repr(num, width=None):
 array(28)
 >>> np.binary_repr(28)
 '11100'
+
 """
 
 bitwise_xor = DPNPBinaryFunc(
@@ -435,7 +447,7 @@ def binary_repr(num, width=None):
 
 
 _INVERT_DOCSTRING = """
-Inverts (flips) each bit for each element `x_i` of the input array `x`.
+Inverts (flips) each bit for each element :math:`x_i` of the input array `x`.
 
 Note that :obj:`dpnp.bitwise_invert` is an alias of :obj:`dpnp.invert`.
 
@@ -444,7 +456,7 @@ def binary_repr(num, width=None):
 Parameters
 ----------
 x : {dpnp.ndarray, usm_ndarray}
-    Input array, expected to have integer or boolean data type.
+    Input array, expected to have an integer or boolean data type.
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -514,9 +526,9 @@ def binary_repr(num, width=None):
 bitwise_invert = invert  # bitwise_invert is an alias for invert
 
 _LEFT_SHIFT_DOCSTRING = """
-Shifts the bits of each element `x1_i` of the input array x1 to the left by
-appending `x2_i` (i.e., the respective element in the input array `x2`) zeros to
-the right of `x1_i`.
+Shifts the bits of each element :math:`x1_i` of the input array `x1` to the
+left by appending :math:`x2_i` (i.e., the respective element in the input array
+`x2`) zeros to the right of :math:`x1_i`.
 
 Note that :obj:`dpnp.bitwise_left_shift` is an alias of :obj:`dpnp.left_shift`.
 
@@ -525,14 +537,10 @@ def binary_repr(num, width=None):
 Parameters
 ----------
 x1 : {dpnp.ndarray, usm_ndarray, scalar}
-    First input array, expected to have integer data type.
-    Both inputs `x1` and `x2` can not be scalars at the same time.
+    First input array, expected to have an integer data type.
 x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array, also expected to have integer data type.
+    Second input array, also expected to have an integer data type.
     Each element must be greater than or equal to ``0``.
-    Both inputs `x1` and `x2` can not be scalars at the same time.
-    If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
-    (which becomes the shape of the output).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -560,6 +568,13 @@ def binary_repr(num, width=None):
 :obj:`dpnp.binary_repr` : Return the binary representation of the input number
                           as a string.
 
+Notes
+-----
+At least one of `x1` or `x2` must be an array.
+
+If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
+(which becomes the shape of the output).
+
 Examples
 --------
 >>> import dpnp as np
@@ -580,6 +595,7 @@ def binary_repr(num, width=None):
 array(20)
 >>> np.binary_repr(20)
 '10100'
+
 """
 
 left_shift = DPNPBinaryFunc(
@@ -594,8 +610,8 @@ def binary_repr(num, width=None):
 
 
 _RIGHT_SHIFT_DOCSTRING = """
-Shifts the bits of each element `x1_i` of the input array `x1` to the right
-according to the respective element `x2_i` of the input array `x2`.
+Shifts the bits of each element :math:`x1_i` of the input array `x1` to the
+right according to the respective element :math:`x2_i` of the input array `x2`.
 
 Note that :obj:`dpnp.bitwise_right_shift` is an alias of :obj:`dpnp.right_shift`.
 
@@ -604,14 +620,10 @@ def binary_repr(num, width=None):
 Parameters
 ----------
 x1 : {dpnp.ndarray, usm_ndarray, scalar}
-    First input array, expected to have integer data type.
-    Both inputs `x1` and `x2` can not be scalars at the same time.
+    First input array, expected to have an integer data type.
 x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array, also expected to have integer data type.
+    Second input array, also expected to have an integer data type.
     Each element must be greater than or equal to ``0``.
-    Both inputs `x1` and `x2` can not be scalars at the same time.
-    If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
-    (which becomes the shape of the output).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -640,6 +652,13 @@ def binary_repr(num, width=None):
 :obj:`dpnp.binary_repr` : Return the binary representation of the input number
                           as a string.
 
+Notes
+-----
+At least one of `x1` or `x2` must be an array.
+
+If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
+(which becomes the shape of the output).
+
 Examples
 --------
 >>> import dpnp as np
@@ -660,6 +679,7 @@ def binary_repr(num, width=None):
 array(5)
 >>> np.binary_repr(5)
 '101'
+
 """
 
 right_shift = DPNPBinaryFunc(

dpnp/dpnp_iface_linearalgebra.py

@@ -617,7 +617,7 @@ def inner(a, b):
 
     See Also
     --------
-    :obj:`dpnp.einsum` : Einstein summation convention..
+    :obj:`dpnp.einsum` : Einstein summation convention.
     :obj:`dpnp.dot` : Generalized matrix product,
                       using second last dimension of `b`.
     :obj:`dpnp.tensordot` : Sum products over arbitrary axes.
@@ -998,7 +998,7 @@ def matvec(
 
     See Also
     --------
-    :obj:`dpnp.vecdot` : Vector-vector product..
+    :obj:`dpnp.vecdot` : Vector-vector product.
     :obj:`dpnp.vecmat` : Vector-matrix product.
     :obj:`dpnp.matmul` : Matrix-matrix product.
     :obj:`dpnp.einsum` : Einstein summation convention.
@@ -1502,7 +1502,7 @@ def vecmat(
 
     See Also
     --------
-    :obj:`dpnp.vecdot` : Vector-vector product..
+    :obj:`dpnp.vecdot` : Vector-vector product.
     :obj:`dpnp.matvec` : Matrix-vector product.
     :obj:`dpnp.matmul` : Matrix-matrix product.
     :obj:`dpnp.einsum` : Einstein summation convention.