!3948 Enhance API comment

Merge pull request !3948 from Simson/enhancement-API

mindspore/ops/__init__.py

@@ -24,8 +24,8 @@ Examples:
 
 Note:
     - The Primitive operators in operations need to be used after instantiation.
-    - The composite operators are pre-defined combination of operator.
-    - The functional operators are the pre-instantiated Primitive operators, which can be used directly like a function.
+    - The composite operators are the pre-defined combination of operators.
+    - The functional operators are the pre-instantiated Primitive operators, which can be used directly as a function.
     - For functional operators usage, please refer to
       https://gitee.com/mindspore/mindspore/blob/master/mindspore/ops/functional.py
 """

mindspore/ops/op_info_register.py

@@ -28,13 +28,14 @@ BUILT_IN_CUSTOM_OPS_REGISTER_PATH = "mindspore/ops/_op_impl/_custom_op"
 
 def op_info_register(op_info):
     """
-    A decorator used as register of operator implementation.
+    A decorator which is used to register an operator.
 
     Note:
-        'op_info' must be a str of json format represent the op info, the op info will be added into oplib.
+        'op_info' should represent the operator information by string with json format.
+        The 'op_info' will be added into oplib.
 
     Args:
-        op_info (str or dict): op info of json format.
+        op_info (str or dict): operator information in json format.
 
     Returns:
         Function, returns a decorator for op info register.
@@ -228,7 +229,7 @@ class AkgRegOp(RegOp):
             index (int): Order of the input. Default: None.
             name (str): Name of the input. Default: None.
             param_type (str): Param type of the input. Default: None.
-            kwargs (dict): Other information for the input.
+            kwargs (dict): Other information of the input.
         """
         param_list = [index, name, param_type]
         key_list = ["index", "name", "param_type"]
@@ -244,7 +245,7 @@ class AkgRegOp(RegOp):
         Args:
             index (int): Order of the output. Default: None.
             name (str): Name of the output. Default: None.
-            kwargs (dict): Other information for the output.
+            kwargs (dict): Other information of the output.
         """
         param_list = [index, name]
         key_list = ["index", "name"]
@@ -261,7 +262,7 @@ class AkgRegOp(RegOp):
             name (str): Name of the attribute. Default: None.
             param_type (str): Param type of the attribute. Default: None.
             value_type (str): Value type of the attribute. Default: None.
-            kwargs (dict): Other information for the attribute.
+            kwargs (dict): Other information of the attribute.
         """
         param_list = [name, param_type, value_type]
         key_list = ["name", "param_type", "type"]
@@ -296,7 +297,7 @@ class AiCPURegOp(RegOp):
             index (int): Order of the input. Default: None.
             name (str): Name of the input. Default: None.
             param_type (str): Param type of the input. Default: None.
-            kwargs (dict): Other information for the input.
+            kwargs (dict): Other information of the input.
         """
         param_list = [index, name, param_type]
         key_list = ["index", "name", "param_type"]
@@ -313,7 +314,7 @@ class AiCPURegOp(RegOp):
             index (int): Order of the output. Default: None.
             name (str): Name of the output. Default: None.
             param_type (str): Param type of the output. Default: None.
-            kwargs (dict): Other information for the output.
+            kwargs (dict): Other information of the output.
         """
         param_list = [index, name, param_type]
         key_list = ["index", "name", "param_type"]
@@ -329,8 +330,8 @@ class AiCPURegOp(RegOp):
         Args:
             name (str): Name of the attribute. Default: None.
             value_type (str): Value type of the attribute. Default: None.
-            value (str): Value type of the attribute. Default: None.
-            kwargs (dict): Other information for the attribute.
+            value (str): Value of the attribute. Default: None.
+            kwargs (dict): Other information of the attribute.
         """
         param_list = [name, value_type, value]
         key_list = ["name", "type", "value"]
@@ -357,7 +358,7 @@ class TBERegOp(RegOp):
 
     def async_flag(self, async_flag):
         """
-        Define the calculation efficiency of operator, whether to support asynchronous calculation.
+        Define the calculation efficiency of the operator, whether the asynchronous calculation is supported.
 
         Args:
             async_flag (bool): Value of async flag. Default: false.
@@ -368,10 +369,10 @@ class TBERegOp(RegOp):
 
     def binfile_name(self, binfile_name):
         """
-        Binary file name of operator. The option is optional.
+        Set the binary file name of the operator, it is optional.
 
         Args:
-            binfile_name (str): File name of operator binary.
+            binfile_name (str): The binary file name of the operator.
         """
         self._is_string(binfile_name)
         self.binfile_name_ = binfile_name
@@ -379,7 +380,7 @@ class TBERegOp(RegOp):
 
     def compute_cost(self, compute_cost):
         """
-        Define the calculation efficiency of operator, which refers to cost model value of the tiling module.
+        Define the calculation efficiency of operator, which refers to the value of the cost model in the tiling module.
 
         Args:
             compute_cost (int): Value of compute cost. Default: 10.
@@ -401,7 +402,7 @@ class TBERegOp(RegOp):
 
     def partial_flag(self, partial_flag):
         """
-        Define the calculation efficiency of operator, whether to support partial calculation.
+        Define the calculation efficiency of operator, whether the partial calculation is supported.
 
         Args:
             partial_flag (bool): Value of partial flag. Default: true.
@@ -423,7 +424,7 @@ class TBERegOp(RegOp):
 
     def dynamic_format(self, dynamic_format):
         """
-        Whether the operator supports dynamic selection of format and dtype.
+        Whether the operator supports dynamic selection of format and dtype or not.
 
         Args:
             dynamic_format (bool): Value of dynamic format. Default: false.
@@ -453,7 +454,7 @@ class TBERegOp(RegOp):
             value_type (str): Type of the attribute. Default: None.
             value (str): Value of the attribute. Default: None.
             default_value (str): Default value of attribute. Default: None.
-            kwargs (dict): Other information for the attribute.
+            kwargs (dict): Other information of the attribute.
         """
         param_list = [name, param_type, value_type, value, default_value]
         key_list = ["name", "param_type", "type", "value", "default_value"]
@@ -469,10 +470,10 @@ class TBERegOp(RegOp):
         Args:
             index (int): Order of the input. Default: None.
             name (str): Name of the input. Default: None.
-            need_compile (bool): The input need compile whether or not. Default: None.
+            need_compile (bool): Whether the input needs to be compiled or not. Default: None.
             param_type (str): Type of the input. Default: None.
             shape (str): Shape of the input. Default: None.
-            kwargs (dict): Other information for the input.
+            kwargs (dict): Other information of the input.
         """
         param_list = [index, name, need_compile, param_type, shape]
         key_list = ["index", "name", "need_compile", "param_type", "shape"]
@@ -488,10 +489,10 @@ class TBERegOp(RegOp):
         Args:
             index (int): Order of the output. Default: None.
             name (str): Name of the output. Default: None.
-            need_compile (bool): The output need compile whether or not. Default: None.
+            need_compile (bool): Whether the output needs to be compiled or not. Default: None.
             param_type (str): Type of the output. Default: None.
             shape (str): Shape of the output. Default: None.
-            kwargs (dict): Other information for the output.
+            kwargs (dict): Other information of the output.
         """
         param_list = [index, name, need_compile, param_type, shape]
         key_list = ["index", "name", "need_compile", "param_type", "shape"]
@@ -505,7 +506,7 @@ class DataType:
     """
     Various combinations of dtype and format.
 
-    The current list below maybe not completed. If necessary, please add it.
+    The current list below may be incomplete. Please add it if necessary.
     """
 
     None_None = ("", "")

mindspore/ops/primitive.py

@@ -28,10 +28,10 @@ from .._c_expression import signature_dtype as sig_dtype
 
 class Primitive(Primitive_):
     """
-    Primitive is base class for primitives in python.
+    Primitive is the base class of primitives in python.
 
     Args:
-        name (str): Name for current Primitive.
+        name (str): Name for the current Primitive.
 
     Examples:
         >>> add = Primitive('add')
@@ -111,11 +111,11 @@ class Primitive(Primitive_):
 
     def set_strategy(self, strategy):
         """
-        Adds strategy to primitive attribute.
+        Add strategies to primitive attribute.
 
         Note:
-            Valid only in semi auto parallel or auto parallel mode.
-            In other parallel modes, strategies will be ignored if set.
+            It is valid only in semi auto parallel or auto parallel mode.
+            In other parallel modes, strategies set here will be ignored.
 
         Args:
             strategy (tuple): Strategy describes the distributed parallel mode of the current primitive.
@@ -125,10 +125,10 @@ class Primitive(Primitive_):
 
     def set_prim_instance_name(self, instance_name):
         """
-        Sets instance name to primitive operator.
+        Set instance name to primitive operator.
 
         Note:
-            Will be called by default when user defines primitive operator.
+            It will be called by default when user defines primitive operator.
 
         Args:
             instance_name (str): Instance name of primitive operator set by user.
@@ -146,14 +146,14 @@ class Primitive(Primitive_):
 
     def check_elim(self, *args):
         """
-        Check whether or not certain inputs should go into backend. Subclass in need should override this method.
+        Check if certain inputs should go to the backend. Subclass in need should override this method.
 
         Args:
             *args(Primitive args): Same as arguments of current Primitive.
 
         Returns:
-            A tuple of two elements, first element indicates whether or not we should filter out current arguments;
-            seconde element is the output in case where we should filter out the arguments.
+            A tuple consisting of two elements. The first element indicates whether we should filter out current
+            arguments; the seconde element is the output if we need to filter out the arguments.
         """
         return (False, None)
 
@@ -181,7 +181,7 @@ class Primitive(Primitive_):
 
     def init_prim_io_names(self, inputs, outputs):
         """
-        Initializes inputs and outpus name of Tensor or attributes.
+        Initializes the name of inputs and outpus of Tensor or attributes.
 
         Args:
             inputs (list[str]): list of inputs names.
@@ -200,15 +200,15 @@ class Primitive(Primitive_):
 
 class PrimitiveWithInfer(Primitive):
     """
-    PrimitiveWithInfer is base class for primitives in python and defines functions for infer of tracks in python.
+    PrimitiveWithInfer is the base class of primitives in python defines functions for tracking inference in python.
 
     There are four method can be overide to define the infer logic of the primitive: __infer__(), infer_shape(),
     infer_dtype(), and infer_value(). If __infer__() is defined in primitive, the __infer__() has highest priority
-    to be called. If __infer__() is not defined, infer_shape() and infer_dtype() can be defined to describe shape
-    and type infer logic. The infer_value() is used for constant propagation.
+    to be called. If __infer__() is not defined, infer_shape() and infer_dtype() can be defined to describe the infer
+    logic of the shape and type. The infer_value() is used for constant propagation.
 
     Args:
-        name (str): Name for current Primitive.
+        name (str): Name of the current Primitive.
 
     Examples:
         >>> # init a Primitive class with infer
@@ -276,7 +276,7 @@ class PrimitiveWithInfer(Primitive):
             args (Any): value of inputs.
 
         Return:
-            Value of outputs. Return `None` for, cat not infer the value at compile time.
+            Value of outputs. Return `None`, the value can not be inferred at compile time in this case.
         """
         return None
 
@@ -295,8 +295,8 @@ def prim_attr_register(fn):
     """
     Primitive attributes register.
 
-    Registering the decorator of the built-in operator primitive __init__
-    function will add all the parameters of __init__ as operator attributes.
+    Register the decorator of the built-in operator primitive '__init__'.
+    The function will add all the parameters of '__init__' as operator attributes.
 
     Args:
         fn (function): __init__ function of primitive.
@@ -325,17 +325,17 @@ def prim_attr_register(fn):
 
 def constexpr(fn=None, get_instance=True, name=None):
     """
-    Makes a PrimitiveWithInfer operator, which infer the value while compiling. We can define a function
+    Makes a PrimitiveWithInfer operator that can infer the value at compile time. We can define a function
     to compute between constant variable and used in constructß.
 
     Args:
         fn (function): A `fn` use as the infer_value of the output operator.
-        get_instance (bool): If true, returns the instance of operator, else returns the operator class.
+        get_instance (bool): If true, return the instance of operator, otherwise return the operator class.
         name (str): Defines the operator name. If `name` is None, use the function name as op name.
 
     Examples:
         >>> a = (1, 2)
-        >>> # make a operator to calculate tuple len
+        >>> # make an operator to calculate tuple len
         >>> @constexpr
         >>> def tuple_len(x):
         >>>     return len(x)

mindspore/ops/vm_impl_registry.py

@@ -37,10 +37,10 @@ Examples:
 
 def get_vm_impl_fn(prim):
     """
-    Gets vm function by primitive obj or primitive name for c++
+    Get the virtual implementation function by a primitive object or primitive name.
 
     Args:
-        prim (Union[Primitive, str]): primitive obj or primitive name for operator register by name.
+        prim (Union[Primitive, str]): primitive object or name for operator register.
 
     Returns:
         function, vm function