!30460 Fix some API docs

Merge pull request !30460 from xiaotianci/modify_api_docs

docs/api/api_python/dataset_vision/mindspore.dataset.vision.Border.rst

@@ -1,7 +1,7 @@
 mindspore.dataset.vision.Border
 ===============================
 
-.. py:class:: mindspore.dataset.vision.Border()
+.. py:class:: mindspore.dataset.vision.Border
 
     边界填充方式枚举类。
 

docs/api/api_python/dataset_vision/mindspore.dataset.vision.ConvertMode.rst

@@ -0,0 +1,29 @@
+mindspore.dataset.vision.ConvertMode
+====================================
+
+.. py:class:: mindspore.dataset.vision.ConvertMode
+
+    图像色彩空间转换模式枚举类。
+
+    可选枚举值如下：
+
+    - **ConvertMode.COLOR_BGR2BGRA** - 将 BGR 图像转换为 BGRA 图像。
+    - **ConvertMode.COLOR_RGB2RGBA** - 将 RGB 图像转换为 RGBA 图像。
+    - **ConvertMode.COLOR_BGRA2BGR** - 将 BGRA 图像转换为 BGR 图像。
+    - **ConvertMode.COLOR_RGBA2RGB** - 将 RGBA 图像转换为 RGB 图像。
+    - **ConvertMode.COLOR_BGR2RGBA** - 将 BGR 图像转换为 RGBA 图像。
+    - **ConvertMode.COLOR_RGB2BGRA** - 将 RGB 图像转换为 BGRA 图像。
+    - **ConvertMode.COLOR_RGBA2BGR** - 将 RGBA 图像转换为 BGR 图像。
+    - **ConvertMode.COLOR_BGRA2RGB** - 将 BGRA 图像转换为 RGB 图像。
+    - **ConvertMode.COLOR_BGR2RGB** - 将 BGR 图像转换为 RGB 图像。
+    - **ConvertMode.COLOR_RGB2BGR** - 将 RGB 图像转换为 BGR 图像。
+    - **ConvertMode.COLOR_BGRA2RGBA** - 将 BGRA 图像转换为 RGBA 图像。
+    - **ConvertMode.COLOR_RGBA2BGRA** - 将 RGBA 图像转换为 BGRA 图像。
+    - **ConvertMode.COLOR_BGR2GRAY** - 将 BGR 图像转换为 GRAY 图像。
+    - **ConvertMode.COLOR_RGB2GRAY** - 将 RGB 图像转换为 GRAY 图像。
+    - **ConvertMode.COLOR_GRAY2BGR** - 将 GRAY 图像转换为 BGR 图像。
+    - **ConvertMode.COLOR_GRAY2RGB** - 将 GRAY 图像转换为 RGB 图像。
+    - **ConvertMode.COLOR_GRAY2BGRA** - 将 GRAY 图像转换为 BGRA 图像。
+    - **ConvertMode.COLOR_GRAY2RGBA** - 将 GRAY 图像转换为 RGBA 图像。
+    - **ConvertMode.COLOR_BGRA2GRAY** - 将 BGRA 图像转换为 GRAY 图像。
+    - **ConvertMode.COLOR_RGBA2GRAY** - 将 RGBA 图像转换为 GRAY 图像。

docs/api/api_python/dataset_vision/mindspore.dataset.vision.ImageBatchFormat.rst

@@ -1,7 +1,7 @@
 mindspore.dataset.vision.ImageBatchFormat
 =========================================
 
-.. py:class:: mindspore.dataset.vision.ImageBatchFormat()
+.. py:class:: mindspore.dataset.vision.ImageBatchFormat
 
     图像批处理输出格式枚举类。
 

docs/api/api_python/dataset_vision/mindspore.dataset.vision.Inter.rst

@@ -1,7 +1,7 @@
 mindspore.dataset.vision.Inter
 ==============================
 
-.. py:class:: mindspore.dataset.vision.Inter()
+.. py:class:: mindspore.dataset.vision.Inter
 
     图像插值方式枚举类。
 

docs/api/api_python/dataset_vision/mindspore.dataset.vision.SliceMode.rst

@@ -2,7 +2,7 @@ mindspore.dataset.vision.SliceMode
 ==================================
 
 .. py:class:: mindspore.dataset.vision.SliceMode
-	
+
     Tensor切片方式枚举类。
 
     可选枚举值为：SliceMode.PAD、SliceMode.DROP。

docs/api/api_python/dataset_vision/mindspore.dataset.vision.py_transforms.Normalize.rst

@@ -9,7 +9,7 @@ mindspore.dataset.vision.py_transforms.Normalize
 
         output_{c} = \frac{input_{c} - mean_{c}}{std_{c}}
 
-    .. note:: 输入图像的像素值需要在[0.0, 1.0]范围内。否则，请先调用 :class:`ToTensor` 进行转换。
+    .. note:: 输入图像的像素值需要在[0.0, 1.0]范围内。否则，请先调用 :class:`mindspore.dataset.vision.py_transforms.ToTensor` 进行转换。
 
     **参数：**
 

docs/api/api_python/dataset_vision/mindspore.dataset.vision.py_transforms.NormalizePad.rst

@@ -11,7 +11,7 @@ mindspore.dataset.vision.py_transforms.NormalizePad
         0, & \text{if} \quad c = 3 \text{.}
         \end{cases}
 
-    .. note:: 输入图像的像素值需要在[0.0, 1.0]范围内。否则，请先调用 :class:`ToTensor` 进行转换。
+    .. note:: 输入图像的像素值需要在[0.0, 1.0]范围内。否则，请先调用 :class:`mindspore.dataset.vision.py_transforms.ToTensor` 进行转换。
 
     **参数：**
 

docs/api/api_python/dataset_vision/mindspore.dataset.vision.py_transforms.Pad.rst

@@ -7,7 +7,7 @@ mindspore.dataset.vision.py_transforms.Pad
 
     **参数：**
 
-    - **padding** (Union[int, sequence]) - 图像各边填充的像素数。若输入整型，将以该值对所有边框进行填充；若输入2元素序列，将以第一个值填充左/上边框，第二个值填充右/下边框；若输入4元素序列，将分别用于填充左、上、右和下边框。
+    - **padding** (Union[int, sequence]) - 图像各边填充的像素数。若输入整型，将以该值对所有边框进行填充；若输入2元素序列，将以第一个值填充左、上边框，第二个值填充右、下边框；若输入4元素序列，将分别用于填充左、上、右和下边框。
     - **fill_value** (Union[int, tuple]，可选) - 用于填充边框的像素值，仅当 `padding_mode` 为 Border.CONSTANT 时生效 。若输入整型，将以该值填充RGB通道；若输入3元素元组，将分别用于填充R、G、B通道。默认值：0。
     - **padding_mode** (Border，可选) - 填充方式，取值可为 Border.CONSTANT、Border.EDGE、Border.REFLECT 或 Border.SYMMETRIC。默认值：Border.CONSTANT。
 
@@ -20,7 +20,7 @@ mindspore.dataset.vision.py_transforms.Pad
 
     - **TypeError** - 当 `padding` 的类型不为整型或整型序列。
     - **TypeError** - 当 `fill_value` 的类型不为整型或整型序列。
-    - **TypeError** - 当 `padding_mode` 的类型不为 :class:`Border` 。
+    - **TypeError** - 当 `padding_mode` 的类型不为 :class:`mindspore.dataset.vision.Border` 。
     - **ValueError** - 当 `padding` 为负数。
     - **ValueError** - 当 `fill_value` 取值不在[0, 255]范围内。
     - **RuntimeError** 当输入图像的shape不为<H, W>或<H, W, C>。

docs/api/api_python/dataset_vision/mindspore.dataset.vision.py_transforms.RandomAffine.rst

@@ -25,7 +25,7 @@ mindspore.dataset.vision.py_transforms.RandomAffine
     - **TypeError** - 当 `translate` 的类型不为序列。
     - **TypeError** - 当 `scale` 的类型不为序列。
     - **TypeError** - 当 `shear` 的类型不为整型、浮点型或序列。
-    - **TypeError** - 当 `resample` 的类型不为 :class:`Inter` 。
+    - **TypeError** - 当 `resample` 的类型不为 :class:`mindspore.dataset.vision.Inter` 。
     - **TypeError** - 当 `fill_value` 的类型不为整型或整型元组。
     - **ValueError** - 当 `degrees` 为负数。
     - **ValueError** - 当 `translate` 取值不在[-1.0, 1.0]范围内。

docs/api/api_python/dataset_vision/mindspore.dataset.vision.py_transforms.RandomCrop.rst

@@ -24,7 +24,7 @@ mindspore.dataset.vision.py_transforms.RandomCrop
     - **TypeError** - 当 `padding` 的类型不为整型或整型序列。
     - **TypeError** - 当 `pad_if_needed` 的类型不为布尔型。
     - **TypeError** - 当 `fill_value` 的类型不为整型或整型序列。
-    - **TypeError** - 当 `padding_mode` 的类型不为 :class:`Border` 。
+    - **TypeError** - 当 `padding_mode` 的类型不为 :class:`mindspore.dataset.vision.Border` 。
     - **ValueError** - 当 `size` 不为正数。
     - **ValueError** - 当 `padding` 为负数。
     - **ValueError** - 当 `fill_value` 取值不在[0, 255]范围内。

docs/api/api_python/dataset_vision/mindspore.dataset.vision.py_transforms.RandomPerspective.rst

@@ -19,6 +19,6 @@ mindspore.dataset.vision.py_transforms.RandomPerspective
 
     - **TypeError** - 当 `distortion_scale` 的类型不为浮点型。
     - **TypeError** - 当 `prob` 的类型不为浮点型。
-    - **TypeError** - 当 `interpolation` 的类型不为 :class:`Inter` 。
+    - **TypeError** - 当 `interpolation` 的类型不为 :class:`mindspore.dataset.vision.Inter` 。
     - **ValueError** - 当 `distortion_scale` 取值不在[0, 1]范围内。
     - **ValueError** - 当 `prob` 取值不在[0, 1]范围内。

docs/api/api_python/dataset_vision/mindspore.dataset.vision.py_transforms.RandomResizedCrop.rst

@@ -24,7 +24,7 @@ mindspore.dataset.vision.py_transforms.RandomResizedCrop
     - **TypeError** - 当 `size` 的类型不为整型或整型序列。
     - **TypeError** - 当 `scale` 的类型不为元组。
     - **TypeError** - 当 `ratio` 的类型不为元组。
-    - **TypeError** - 当 `interpolation` 的类型不为 :class:`Inter` 。
+    - **TypeError** - 当 `interpolation` 的类型不为 :class:`mindspore.dataset.vision.Inter` 。
     - **TypeError** - 当 `max_attempts` 的类型不为整型。
     - **ValueError** - 当 `size` 不为正数。
     - **ValueError** - 当 `scale` 为负数。

docs/api/api_python/dataset_vision/mindspore.dataset.vision.py_transforms.RandomRotation.rst

@@ -24,7 +24,7 @@ mindspore.dataset.vision.py_transforms.RandomRotation
     **异常：**
 
     - **TypeError** - 当 `degrees` 的类型不为整型、浮点型或序列。
-    - **TypeError** - 当 `resample` 的类型不为 :class:`Inter` 。
+    - **TypeError** - 当 `resample` 的类型不为 :class:`mindspore.dataset.vision.Inter` 。
     - **TypeError** - 当 `expand` 的类型不为布尔型。
     - **TypeError** - 当 `center` 的类型不为元组。
     - **TypeError** - 当 `fill_value` 的类型不为整型或整型序列。

docs/api/api_python/dataset_vision/mindspore.dataset.vision.py_transforms.Resize.rst

@@ -18,5 +18,5 @@ mindspore.dataset.vision.py_transforms.Resize
     **异常：**
 
     - **TypeError** - 当 `size` 的类型不为整型或整型序列。
-    - **TypeError** - 当 `interpolation` 的类型不为 :class:`Inter` 。
+    - **TypeError** - 当 `interpolation` 的类型不为 :class:`mindspore.dataset.vision.Inter` 。
     - **ValueError** - 当 `size` 不为正数。

docs/api/api_python/dataset_vision/mindspore.dataset.vision.py_transforms.ToTensor.rst

@@ -9,9 +9,9 @@ mindspore.dataset.vision.py_transforms.ToTensor
 
     **参数：**
 
-    - **output_type** (numpy.dtype，可选) - 输出图像的数据类型，默认值：numpy.float32。
+    - **output_type** (numpy.dtype，可选) - 输出图像的数据类型，默认值：:class:`numpy.float32`。
 
     **异常：**
 
-    - **TypeError** - 当输入图像的类型不为 :class:`numpy.ndarray` 或 :class:`PIL.Image` 。
+    - **TypeError** - 当输入图像的类型不为 :class:`PIL.Image` 或 :class:`numpy.ndarray` 。
     - **TypeError** - 输入图像的维度不为2或3。

docs/api/api_python/dataset_vision/mindspore.dataset.vision.py_transforms.ToType.rst

@@ -7,7 +7,7 @@ mindspore.dataset.vision.py_transforms.ToType
 
     **参数：**
 
-    - **output_type** (numpy.dtype) - 输出图像的数据类型，例如numpy.float32。
+    - **output_type** (numpy.dtype) - 输出图像的数据类型，例如 :class:`numpy.float32` 。
 
     **异常：**
 

mindspore/python/mindspore/dataset/audio/utils.py

@@ -207,9 +207,9 @@ def create_dct(n_mfcc, n_mels, norm=NormMode.NONE):
         numpy.ndarray, the transformation matrix, to be right-multiplied to row-wise data of size (n_mels, n_mfcc).
 
     Examples:
-        >>> from mindspore.dataset.audio import create_dct
+        >>> from mindspore.dataset.audio import create_dct, NormMode
         >>>
-        >>> dct = create_dct(100, 200, audio.NormMode.NONE)
+        >>> dct = create_dct(100, 200, NormMode.NONE)
     """
 
     if not isinstance(n_mfcc, int):

mindspore/python/mindspore/dataset/callback/ds_callback.py

@@ -35,14 +35,15 @@ class DSCallback:
 
     Examples:
         >>> from mindspore.dataset import DSCallback
+        >>> from mindspore.dataset.transforms import c_transforms
         >>>
         >>> class PrintInfo(DSCallback):
         ...     def ds_epoch_end(self, ds_run_context):
         ...         print(ds_run_context.cur_epoch_num)
         ...         print(ds_run_context.cur_step_num)
         >>>
-        >>> # dataset is a MindSpore dataset object and op is a certain data processing operator
-        >>> op = c_transforms.Fill(3)
+        >>> dataset = ds.MnistDataset(mnist_dataset_dir, num_samples=100)
+        >>> op = c_transforms.OneHot(10)
         >>> dataset = dataset.map(operations=op, callbacks=PrintInfo())
     """
 
@@ -126,10 +127,10 @@ class DSCallback:
 
 
 class WaitedDSCallback(Callback, DSCallback):
-    """
+    r"""
     Abstract base class used to build dataset callback classes that are synchronized with the training callback class
-    `mindspore.train.callback <https://mindspore.cn/docs/api/en/master/api_python/
-    mindspore.train.html#mindspore.train.callback.Callback>`_.
+    `mindspore.train.callback \
+    <https://mindspore.cn/docs/api/en/master/api_python/mindspore.train.html#mindspore.train.callback.Callback>`_.
 
     It can be used to execute a custom callback method before a step or an epoch, such as
     updating the parameters of operators according to the loss of the previous training epoch in auto augmentation.
@@ -140,8 +141,8 @@ class WaitedDSCallback(Callback, DSCallback):
     `network`, `train_network`, `epoch_num`, `batch_num`, `loss_fn`, `optimizer`, `parallel_mode`,
     `device_number`, `list_callback`, `cur_epoch_num`, `cur_step_num`, `dataset_sink_mode`,
     `net_outputs`, etc., see
-    `mindspore.train.callback <https://mindspore.cn/docs/api/en/master/api_python/
-    mindspore.train.html#mindspore.train.callback.Callback>`_.
+    `mindspore.train.callback \
+    <https://mindspore.cn/docs/api/en/master/api_python/mindspore.train.html#mindspore.train.callback.Callback>`_.
 
     Users can obtain the dataset pipeline context through `ds_run_context`, including
     `cur_epoch_num`, `cur_step_num_in_epoch` and `cur_step_num`.

mindspore/python/mindspore/dataset/engine/cache_client.py

@@ -47,7 +47,7 @@ class DatasetCache:
             >>> # In the following code, suppose the session_id is 780643335
             >>> some_cache = ds.DatasetCache(session_id=780643335, size=0)
             >>>
-            >>> dataset_dir = "path/to/imagefolder_directory"
+            >>> dataset_dir = "/path/to/imagefolder_directory"
             >>> ds1 = ds.ImageFolderDataset(dataset_dir, cache=some_cache)
     """
 

mindspore/python/mindspore/dataset/engine/datasets_text.py

@@ -990,7 +990,7 @@ class IWSLT2017Dataset(SourceDataset, TextBaseDataset):
         RuntimeError: If `shard_id` is specified but `num_shards` is None.
 
     Examples:
-        >>> iwslt2017_dataset_dir = "/path/to/iwslt207_dataset_dir"
+        >>> iwslt2017_dataset_dir = "/path/to/iwslt2017_dataset_dir"
         >>> dataset = ds.IWSLT2017Dataset(dataset_dir=iwslt2017_dataset_dir, usage='all', language_pair=('de', 'en'))
 
     About IWSLT2017 dataset:

mindspore/python/mindspore/dataset/engine/serializer_deserializer.py

@@ -43,11 +43,10 @@ def serialize(dataset, json_filepath=""):
     Examples:
         >>> dataset = ds.MnistDataset(mnist_dataset_dir, num_samples=100)
         >>> one_hot_encode = c_transforms.OneHot(10)  # num_classes is input argument
-        >>> dataset = dataset.map(operation=one_hot_encode, input_column_names="label")
+        >>> dataset = dataset.map(operations=one_hot_encode, input_columns="label")
         >>> dataset = dataset.batch(batch_size=10, drop_remainder=True)
         >>> # serialize it to JSON file
-        >>> ds.serialize(dataset, json_filepath="/path/to/mnist_dataset_pipeline.json")
-        >>> serialized_data = ds.serialize(dataset)  # serialize it to Python dict
+        >>> serialized_data = ds.serialize(dataset, json_filepath="/path/to/mnist_dataset_pipeline.json")
     """
     return dataset.to_json(json_filepath)
 
@@ -72,16 +71,16 @@ def deserialize(input_dict=None, json_filepath=None):
     Examples:
         >>> dataset = ds.MnistDataset(mnist_dataset_dir, num_samples=100)
         >>> one_hot_encode = c_transforms.OneHot(10)  # num_classes is input argument
-        >>> dataset = dataset.map(operation=one_hot_encode, input_column_names="label")
+        >>> dataset = dataset.map(operations=one_hot_encode, input_columns="label")
         >>> dataset = dataset.batch(batch_size=10, drop_remainder=True)
-        >>> # Use case 1: to/from JSON file
-        >>> ds.serialize(dataset, json_filepath="/path/to/mnist_dataset_pipeline.json")
-        >>> dataset = ds.deserialize(json_filepath="/path/to/mnist_dataset_pipeline.json")
-        >>> # Use case 2: to/from Python dictionary
+        >>> # Case 1: to/from JSON file
+        >>> serialized_data = ds.serialize(dataset, json_filepath="/path/to/mnist_dataset_pipeline.json")
+        >>> deserialized_dataset = ds.deserialize(json_filepath="/path/to/mnist_dataset_pipeline.json")
+        >>> # Case 2: to/from Python dictionary
         >>> serialized_data = ds.serialize(dataset)
-        >>> dataset = ds.deserialize(input_dict=serialized_data)
-
+        >>> deserialized_dataset = ds.deserialize(input_dict=serialized_data)
     """
+
     data = None
     if input_dict:
         data = de.DeserializedDataset(input_dict)
@@ -133,7 +132,7 @@ def compare(pipeline1, pipeline2):
 
     Examples:
         >>> pipeline1 = ds.MnistDataset(mnist_dataset_dir, num_samples=100)
-        >>> pipeline2 = ds.Cifar10Dataset(cifar_dataset_dir, num_samples=100)
+        >>> pipeline2 = ds.Cifar10Dataset(cifar10_dataset_dir, num_samples=100)
         >>> res = ds.compare(pipeline1, pipeline2)
     """
 

mindspore/python/mindspore/mindrecord/filewriter.py

@@ -128,7 +128,7 @@ class FileWriter:
             >>> schema_json = {"file_name": {"type": "string"}, "label": {"type": "int32"}, "data": {"type": "bytes"}}
             >>> data = [{"file_name": "1.jpg", "label": 0,
             ...          "data": b"\x10c\xb3w\xa8\xee$o&<q\x8c\x8e(\xa2\x90\x90\x96\xbc\xb1\x1e\xd4QER\x13?\xff"}]
-            >>> writer = FileWriter(file_name="test.mindrecord", shard_num=1)
+            >>> writer = FileWriter(file_name="test.mindrecord", shard_num=1, overwrite=True)
             >>> writer.add_schema(schema_json, "test_schema")
             0
             >>> writer.write_raw_data(data)