FIx issue #12470: update operator descriptions

mindspore/ops/operations/array_ops.py

@@ -162,7 +162,9 @@ class DType(PrimitiveWithInfer):
 
     Examples:
         >>> input_tensor = Tensor(np.array([[2, 2], [2, 2]]), mindspore.float32)
-        >>> type = P.DType()(input_tensor)
+        >>> output = P.DType()(input_tensor)
+        >>> print(output)
+        Float32
     """
 
     @prim_attr_register
@@ -238,7 +240,11 @@ class Cast(PrimitiveWithInfer):
         >>> input_x = Tensor(input_np)
         >>> type_dst = mindspore.float16
         >>> cast = P.Cast()
-        >>> result = cast(input_x, type_dst)
+        >>> output = cast(input_x, type_dst)
+        >>> print(output.dtype)
+        Float16
+        >>> print(output.shape)
+        (2, 3, 4, 5)
     """
 
     @prim_attr_register
@@ -2476,10 +2482,10 @@ class DiagPart(PrimitiveWithInfer):
     :math:`output[i_1,..., i_k] = input[i_1,..., i_k, i_1,..., i_k]`.
 
     Inputs:
-        - **input_x** (Tensor) - The input Tensor.
+        - **input_x** (Tensor) - tensor of rank k where k is even and not zero.
 
     Outputs:
-        Tensor.
+        Tensor, the extracted diagonal has the same dtype as the `input_x`.
 
     Examples
         >>> input_x = Tensor([[1, 0, 0, 0],
@@ -2487,7 +2493,8 @@ class DiagPart(PrimitiveWithInfer):
         >>>                   [0, 0, 3, 0],
         >>>                   [0, 0, 0, 4]])
         >>> diag_part = P.DiagPart()
-        >>> diag_part(input_x)
+        >>> output = diag_part(input_x)
+        >>> print(output)
         [1, 2, 3, 4]
     """
 
@@ -3215,17 +3222,18 @@ class DepthToSpace(PrimitiveWithInfer):
         block_size (int): The block size used to divide depth data. It must be >= 2.
 
     Inputs:
-        - **x** (Tensor) - The target tensor. It must be a 4-D tensor.
+        - **x** (Tensor) - The target tensor. It must be a 4-D tensor with shape :math:`(N, C_{in}, H_{in}, W_{in})`.
 
     Outputs:
-        Tensor, has the same shape and dtype as the 'x'.
+        Tensor of shape :math:`(N, C_{in} / \text{block_size}, H_{in} * \text{block_size}, W_{in} * \text{block_size})`.
 
     Examples:
         >>> x = Tensor(np.random.rand(1,12,1,1), mindspore.float32)
         >>> block_size = 2
         >>> op = P.DepthToSpace(block_size)
         >>> output = op(x)
-        >>> output.asnumpy().shape == (1,3,2,2)
+        >>> print(output.shape)
+        (1, 3, 2, 2)
     """
 
     @prim_attr_register

mindspore/ops/operations/control_ops.py

@@ -33,8 +33,8 @@ class ControlDepend(Primitive):
     Note:
         This operation does not work in `PYNATIVE_MODE`.
     Args:
-        depend_mode (int): Use 0 for a normal dependency relation. Use 1 to depends on operations which using Parameter
-        as its input. Default: 0.
+        depend_mode (int): Use 0 for a normal dependency relation and 1 for a user-defined dependency relation.
+        Default: 0.
 
     Inputs:
         - **src** (Any) - The source input. It can be a tuple of operations output or a single operation output. We do
@@ -47,7 +47,7 @@ class ControlDepend(Primitive):
           used the parameter as input.
 
     Outputs:
-        Bool. This operation has no actual data output, it will be used to setup the order of relative operations.
+        This operation has no actual data output, it will be used to setup the order of relative operations.
 
     Examples:
         >>> class Net(nn.Cell):
@@ -65,6 +65,13 @@ class ControlDepend(Primitive):
         >>> y = Tensor(np.ones([4, 5]), dtype=mindspore.float32)
         >>> net = Net()
         >>> output = net(x, y)
+        >>> print(output)
+        [[1.	1.	1.	1.	1.]
+         [1.	1.	1.	1.	1.]
+         [1.	1.	1.	1.	1.]
+         [1.	1.	1.	1.	1.]]
+        >>> print(output.dtype)
+        Float32
     """
 
     @prim_attr_register

mindspore/ops/operations/math_ops.py

@@ -596,15 +596,26 @@ class CumProd(PrimitiveWithInfer):
         Tensor, has the same shape and dtype as the `input_x`.
 
     Examples:
+        >>> a = 1
+        >>> b = 2
+        >>> c = 3
         >>> input_x = Tensor(np.array([a, b, c]).astype(np.float32))
         >>> op0 = P.CumProd()
-        >>> output = op0(input_x, 0) # output=[a, a * b, a * b * c]
+        >>> output0 = op0(input_x, 0) # output=[a, a * b, a * b * c]
         >>> op1 = P.CumProd(exclusive=True)
-        >>> output = op1(input_x, 0) # output=[1, a, a * b]
+        >>> output1 = op1(input_x, 0) # output=[1, a, a * b]
         >>> op2 = P.CumProd(reverse=True)
-        >>> output = op2(input_x, 0) # output=[a * b * c, b * c, c]
+        >>> output2 = op2(input_x, 0) # output=[a * b * c, b * c, c]
         >>> op3 = P.CumProd(exclusive=True, reverse=True)
-        >>> output = op3(input_x, 0) # output=[b * c, c, 1]
+        >>> output3 = op3(input_x, 0) # output=[b * c, c, 1]
+        >>> print(output0)
+        [1. 2. 6.]
+        >>> print(output1)
+        [1. 1. 2.]
+        >>> print(output2)
+        [6. 6. 3.]
+        >>> print(output3)
+        [6. 3. 1.]
     """
 
     @prim_attr_register
@@ -3028,6 +3039,8 @@ class Cos(PrimitiveWithInfer):
         >>> cos = P.Cos()
         >>> input_x = Tensor(np.array([0.24, 0.83, 0.31, 0.09]), mindspore.float32)
         >>> output = cos(input_x)
+        >>> print(output)
+        [0.971338	0.67487574	0.95233357	0.9959527 ]
     """
 
     @prim_attr_register

mindspore/ops/operations/nn_ops.py

@@ -984,22 +984,21 @@ class Conv2D(PrimitiveWithInfer):
         group (int): Splits input into groups. Default: 1.
         data_format (str): The optional value for data format, is 'NHWC' or 'NCHW'. Default: "NCHW".
 
-    Returns:
-        Tensor, the value that applied 2D convolution.
-
     Inputs:
         - **input** (Tensor) - Tensor of shape :math:`(N, C_{in}, H_{in}, W_{in})`.
         - **weight** (Tensor) - Set size of kernel is :math:`(K_1, K_2)`, then the shape is
           :math:`(C_{out}, C_{in}, K_1, K_2)`.
 
     Outputs:
-        Tensor of shape :math:`(N, C_{out}, H_{out}, W_{out})`.
+        Tensor, the value that applied 2D convolution. The shape is :math:`(N, C_{out}, H_{out}, W_{out})`.
 
     Examples:
         >>> input = Tensor(np.ones([10, 32, 32, 32]), mindspore.float32)
         >>> weight = Tensor(np.ones([32, 32, 3, 3]), mindspore.float32)
         >>> conv2d = P.Conv2D(out_channel=32, kernel_size=3)
-        >>> conv2d(input, weight)
+        >>> output = conv2d(input, weight)
+        >>> print(output.shape)
+        (10, 32, 30, 30)
     """
 
     @prim_attr_register
@@ -1143,7 +1142,8 @@ class DepthwiseConv2dNative(PrimitiveWithInfer):
         >>> weight = Tensor(np.ones([1, 32, 3, 3]), mindspore.float32)
         >>> depthwise_conv2d = P.DepthwiseConv2dNative(channel_multiplier = 3, kernel_size = (3, 3))
         >>> output = depthwise_conv2d(input, weight)
-        >>> output.shape == (10, 96, 30, 30)
+        >>> print(output.shape)
+        (10, 96, 30, 30)
     """
 
     @prim_attr_register
@@ -1537,15 +1537,25 @@ class Conv2DBackpropInput(PrimitiveWithInfer):
         data_format (str) - The format of input and output data. It should be 'NHWC' or 'NCHW'，\
             default is 'NCHW'.
 
-    Returns:
-        Tensor, the gradients of convolution.
+    Inputs:
+        - **dout** (Tensor) - the gradients w.r.t the output of the convolution. The shape conforms to the default
+          data_format :math:`(N, C_{out}, H_{out}, W_{out})`.
+        - **weight** (Tensor) - Set size of kernel is :math:`(K_1, K_2)`, then the shape is
+          :math:`(C_{out}, C_{in}, K_1, K_2)`.
+        - **input_size** (Tensor) - A tuple describes the shape of the input which conforms to the format
+          :math:`(N, C_{in}, H_{in}, W_{in})`.
+
+    Outputs:
+        Tensor, the gradients w.r.t the input of convolution. It has the same shape as the input.
 
     Examples:
         >>> dout = Tensor(np.ones([10, 32, 30, 30]), mindspore.float32)
         >>> weight = Tensor(np.ones([32, 32, 3, 3]), mindspore.float32)
         >>> x = Tensor(np.ones([10, 32, 32, 32]))
         >>> conv2d_backprop_input = P.Conv2DBackpropInput(out_channel=32, kernel_size=3)
-        >>> conv2d_backprop_input(dout, weight, F.shape(x))
+        >>> output = conv2d_backprop_input(dout, weight, F.shape(x))
+        >>> print(output.shape)
+        (10, 32, 32, 32)
     """
 
     @prim_attr_register
@@ -5328,15 +5338,20 @@ class Dropout(PrimitiveWithInfer):
           means dropping out 10% of input units.
 
     Inputs:
-        - **shape** (tuple[int]) - The shape of target mask.
+        - **input** (Tensor) - The input tensor.
 
     Outputs:
-        Tensor, the value of generated mask for input shape.
+        - **output** (Tensor) - with the same shape as the input tensor.
+        - **mask** (Tensor) - with the same shape as the input tensor.
 
     Examples:
         >>> dropout = P.Dropout(keep_prob=0.5)
-        >>> in = Tensor((20, 16, 50, 50))
-        >>> out = dropout(in)
+        >>> x = Tensor((20, 16, 50, 50), mindspore.float32)
+        >>> output, mask = dropout(x)
+        >>> print(output)
+        [ 0.	32.	0.	0.]
+        >>> print(mask)
+        [0.	1.	0.	0.]
     """
 
     @prim_attr_register
@@ -5390,7 +5405,15 @@ class CTCLoss(PrimitiveWithInfer):
         >>> labels_values = Tensor(np.array([2, 2]), mindspore.int32)
         >>> sequence_length = Tensor(np.array([2, 2]), mindspore.int32)
         >>> ctc_loss = P.CTCLoss()
-        >>> output = ctc_loss(inputs, labels_indices, labels_values, sequence_length)
+        >>> loss, gradient = ctc_loss(inputs, labels_indices, labels_values, sequence_length)
+        >>> print(loss)
+        [0.69121575	0.5381993 ]
+        >>> print(gradient)
+        [[[ 0.25831494	0.3623634	-0.62067937]
+          [ 0.25187883	0.2921483	-0.5440271 ]]
+
+         [[ 0.43522435	0.24408469	0.07787037 ]
+          [ 0.29642645	0.4232373 	0.06138104 ]]]
     """
 
     @prim_attr_register

mindspore/ops/operations/other_ops.py

@@ -215,7 +215,7 @@ class CheckValid(PrimitiveWithInfer):
           Data type must be float16 or float32.
 
     Outputs:
-        Tensor, the valided tensor.
+        Tensor, with shape of (N,) and dtype of bool.
 
     Examples:
         >>> import mindspore
@@ -234,7 +234,8 @@ class CheckValid(PrimitiveWithInfer):
         >>> bboxes = Tensor(np.linspace(0, 6, 12).reshape(3, 4), mindspore.float32)
         >>> img_metas = Tensor(np.array([2, 1, 3]), mindspore.float32)
         >>> net = Net()
-        >>> result = net(bboxes, img_metas)
+        >>> output = net(bboxes, img_metas)
+        >>> print(output)
         [True   False   False]
     """
 
@@ -381,6 +382,9 @@ class Depend(Primitive):
     """
     Depend is used for processing side-effect operations.
 
+    Note:
+        Internal API, not for public use.
+
     Inputs:
         - **value** (Tensor) - the real value to return for depend operator.
         - **expr** (Expression) - the expression to execute with no outputs.