Update descriptions of functions in RandomState class (#1264)

Author: antonwolfy

dpnp/random/dpnp_random_state.py

@@ -57,6 +57,22 @@ class RandomState:
     A container for the Mersenne Twister pseudo-random number generator.
 
     For full documentation refer to :obj:`numpy.random.RandomState`.
+
+    Parameters
+    ----------
+    device : {None, string, SyclDevice, SyclQueue}, optional
+        An array API concept of device where the output array is created.
+        `device` can be ``None`` (the default), a oneAPI filter selector string,
+        an instance of :class:`dpctl.SyclDevice` corresponding to a non-partitioned SYCL device,
+        an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by
+        :obj:`dpnp.dpnp_array.dpnp_array.device` property.
+    sycl_queue : {None, SyclQueue}, optional
+        The SYCL queue to use for output array allocation and copying.
+
+    Limitations
+    -----------
+    Parameter `seed` is supported as either a integer scalar or array_like
+    of maximumum three integer scalars.
     """
 
     def __init__(self, seed=None, device=None, sycl_queue=None):
@@ -107,9 +123,9 @@ def _is_signbit_scalar(self, x):
 
     def _validate_float_dtype(self, dtype, supported_types):
         """
-        Test an input floating type if it is listed in ``supported_types`` and
+        Test an input floating type if it is listed in `supported_types` and
         if it is supported by the used SYCL device.
-        If ``dtype`` is None, default floating type will be validating.
+        If `dtype` is ``None``, default floating type will be validating.
         Return the examined floating type if it follows all validation checks.
         """
 
@@ -139,7 +155,7 @@ def get_state(self):
 
     def get_sycl_queue(self):
         """
-        Return an instance of of :class:`dpctl.SyclQueue` used within the generator for data allocation.
+        Return an instance of :class:`dpctl.SyclQueue` used within the generator for data allocation.
 
         Returns
         -------
@@ -151,7 +167,7 @@ def get_sycl_queue(self):
 
     def get_sycl_device(self):
         """
-        Return an instance of of :class:`dpctl.SyclDevice` used within the generator to allocate data on.
+        Return an instance of :class:`dpctl.SyclDevice` used within the generator to allocate data on.
 
         Returns
         -------
@@ -169,25 +185,24 @@ def normal(self, loc=0.0, scale=1.0, size=None, dtype=None, usm_type="device"):
 
         Parameters
         ----------
-        usm_type : ("device" | "shared" | "host"), optional
+        usm_type : {"device", "shared", "host"}, optional
             The type of SYCL USM allocation for the output array.
 
         Returns
         -------
         out : dpnp.ndarray
             Drawn samples from the parameterized normal distribution.
-            Output array data type is the same as input ``dtype``. If ``dtype`` is None (default),
-            :obj:`dpnp.float64` type will be used if device supports it or :obj:`dpnp.float32` otherwise.
+            Output array data type is the same as input `dtype`. If `dtype` is ``None`` (the default),
+            :obj:`dpnp.float64` type will be used if device supports it, or :obj:`dpnp.float32` otherwise.
 
         Limitations
         -----------
-        Parameters ``loc`` and ``scale`` are supported as scalar. Otherwise,
+        Parameters `loc` and `scale` are supported as scalar. Otherwise,
         :obj:`numpy.random.RandomState.normal(loc, scale, size)` samples are drawn.
-        Parameter ``dtype`` is supported only for :obj:`dpnp.float32`, :obj:`dpnp.float64` or `None`.
+        Parameter `dtype` is supported only as :obj:`dpnp.float32`, :obj:`dpnp.float64` or ``None``.
 
         Examples
         --------
-        Draw samples from the distribution:
         >>> s = dpnp.random.RandomState().normal(loc=3.7, scale=2.5, size=(2, 4))
         >>> print(s)
         [[ 1.58997253 -0.84288406  2.33836967  4.16394577]
@@ -241,14 +256,14 @@ def rand(self, *args, usm_type="device"):
 
         Parameters
         ----------
-        usm_type : ("device" | "shared" | "host"), optional
+        usm_type : {"device", "shared", "host"}, optional
             The type of SYCL USM allocation for the output array.
 
         Returns
         -------
         out : dpnp.ndarray
             Random values in a given shape.
-            Output array data type is :obj:`dpnp.float64` if device supports it or :obj:`dpnp.float32` otherwise.
+            Output array data type is :obj:`dpnp.float64` if device supports it, or :obj:`dpnp.float32` otherwise.
 
         Examples
         --------
@@ -284,21 +299,21 @@ def randint(self, low, high=None, size=None, dtype=int, usm_type="device"):
 
         Parameters
         ----------
-        usm_type : ("device" | "shared" | "host"), optional
+        usm_type : {"device", "shared", "host"}, optional
             The type of SYCL USM allocation for the output array.
 
         Returns
         -------
         out : dpnp.ndarray
             `size`-shaped array of random integers from the appropriate distribution,
-            or a single such random int if `size` not provided.
-            Output array data type is the same as input ``dtype``.
+            or a single such random int if `size` is not provided.
+            Output array data type is the same as input `dtype`.
 
         Limitations
         -----------
-        Parameters ``low`` and ``high`` are supported only as scalar.
-        Parameter ``dtype`` is supported only as :obj:`dpnp.int32` or `int`,
-        but `int` value is considered to be exactly equivalent to :obj:`dpnp.int32`.
+        Parameters `low` and `high` are supported only as a scalar.
+        Parameter `dtype` is supported only as :obj:`dpnp.int32` or ``int``,
+        but ``int`` value is considered to be exactly equivalent to :obj:`dpnp.int32`.
         Otherwise, :obj:`numpy.random.randint(low, high, size, dtype)` samples are drawn.
 
         Examples
@@ -359,16 +374,16 @@ def randn(self, *args, usm_type="device"):
 
         Parameters
         ----------
-        usm_type : ("device" | "shared" | "host"), optional
+        usm_type : {"device", "shared", "host"}, optional
             The type of SYCL USM allocation for the output array.
 
         Returns
         -------
-        Z : dpnp.ndarray
+        out : dpnp.ndarray
             A ``(d0, d1, ..., dn)``-shaped array of floating-point samples from
             the standard normal distribution, or a single such float if
             no parameters were supplied.
-            Output array data type is :obj:`dpnp.float64` if device supports it
+            Output array data type is :obj:`dpnp.float64` if device supports it,
             or :obj:`dpnp.float32` otherwise.
 
         Examples
@@ -408,15 +423,15 @@ def random_sample(self, size=None, usm_type="device"):
 
         Parameters
         ----------
-        usm_type : ("device" | "shared" | "host"), optional
+        usm_type : {"device", "shared", "host"}, optional
             The type of SYCL USM allocation for the output array.
 
         Returns
         -------
         out : dpnp.ndarray
             Array of random floats of shape `size` (if ``size=None``,
             zero dimension array with a single float is returned).
-            Output array data type is :obj:`dpnp.float64` if device supports it
+            Output array data type is :obj:`dpnp.float64` if device supports it,
             or :obj:`dpnp.float32` otherwise.
 
         Examples
@@ -447,20 +462,19 @@ def standard_normal(self, size=None, usm_type="device"):
 
         Parameters
         ----------
-        usm_type : ("device" | "shared" | "host"), optional
+        usm_type : {"device", "shared", "host"}, optional
             The type of SYCL USM allocation for the output array.
 
         Returns
         -------
         out : dpnp.ndarray
-            A floating-point array of shape ``size`` of drawn samples, or a
-            single sample if ``size`` was not specified.
-            Output array data type is :obj:`dpnp.float64` if device supports it
+            A floating-point array of shape `size` of drawn samples, or a
+            single sample if `size` was not specified.
+            Output array data type is :obj:`dpnp.float64` if device supports it,
             or :obj:`dpnp.float32` otherwise.
 
         Examples
         --------
-        Draw samples from the distribution:
         >>> s = dpnp.random.RandomState().standard_normal(size=(3, 5))
         >>> print(s)
         [[-0.84401099 -1.81715362 -0.54465213  0.18557831  0.28352814]
@@ -492,25 +506,24 @@ def uniform(self, low=0.0, high=1.0, size=None, dtype=None, usm_type="device"):
 
         Parameters
         ----------
-        usm_type : ("device" | "shared" | "host"), optional
+        usm_type : {"device", "shared", "host"}, optional
             The type of SYCL USM allocation for the output array.
 
         Returns
         -------
         out : dpnp.ndarray
             Drawn samples from the parameterized uniform distribution.
-            Output array data type is the same as input ``dtype``. If ``dtype`` is None (default),
-            :obj:`dpnp.float64` type will be used if device supports it or :obj:`dpnp.float32` otherwise.
+            Output array data type is the same as input `dtype`. If `dtype` is ``None`` (the default),
+            :obj:`dpnp.float64` type will be used if device supports it, or :obj:`dpnp.float32` otherwise.
 
         Limitations
         -----------
-        Parameters ``low`` and ``high`` are supported as scalar. Otherwise,
+        Parameters `low` and `high` are supported as scalar. Otherwise,
         :obj:`numpy.random.uniform(low, high, size)` samples are drawn.
-        Parameter ``dtype`` is supported only for :obj:`dpnp.int32`, :obj:`dpnp.float32`, :obj:`dpnp.float64` or `None`.
+        Parameter `dtype` is supported only as :obj:`dpnp.int32`, :obj:`dpnp.float32`, :obj:`dpnp.float64` or ``None``.
 
         Examples
         --------
-        Draw samples from the distribution:
         >>> low, high = 1.23, 10.54    # low and high
         >>> s = dpnp.random.RandomState().uniform(low, high, 5)
         >>> print(s)