!27180 modify api annotation

Merge pull request !27180 from xumengjuan1/code_docs_xmj3

docs/api/api_python/mindspore.nn/mindspore.nn.ForwardValueAndGrad.txt

@@ -1,39 +1,37 @@
-Class mindspore.nn.ForwardValueAndGrad(network, weights=None, get_all=False, get_by_list=False, sens_param=False)
+mindspore.nn.ForwardValueAndGrad
+===================================
+
+.. py:class:: mindspore.nn.ForwardValueAndGrad(network, weights=None, get_all=False, get_by_list=False, sens_param=False)
 
     网络训练包类。
 
     包括正向网络和梯度函数。该类生成的Cell使用'\*inputs'输入来训练。
     通过梯度函数来创建反向图，用以计算梯度。
 
-    参数：
-        network (Cell)：训练网络。
-        weights (ParameterTuple)：训练网络中需要计算梯度的的参数。
-        get_all (bool)：如果为True，则计算网络输入对应的梯度。默认值：False。
-        get_by_list (bool)：如果为True，则计算参数变量对应的梯度。
-            如果get_all和get_by_list都为False，则计算第一个输入对应的梯度。
-            如果get_all和get_by_list都为True，则以（（输入的梯度）,（参数的梯度））的形式同时获取输入和参数变量的梯度。
+    **参数：**
     
-            默认值：False。
-        sens_param (bool)：是否将sens作为输入。
-            如果sens_param为False，则sens默认为'ones_like(outputs)'。
-            默认值：False。
-            如果sens_param为True，则需要指定sens的值。
+    - **network** (Cell) - 训练网络。
+    - **weights** (ParameterTuple) - 训练网络中需要计算梯度的的参数。
+    - **get_all** (bool) - 如果为True，则计算网络输入对应的梯度。默认值：False。
+    - **get_by_list** (bool) - 如果为True，则计算参数变量对应的梯度。如果 `get_all` 和 `get_by_list` 都为False，则计算第一个输入对应的梯度。如果 `get_all` 和 `get_by_list` 都为True，则以（（输入的梯度）,（参数的梯度））的形式同时获取输入和参数变量的梯度。默认值：False。
+    - **sens_param** (bool) - 是否将sens作为输入。如果 `sens_param` 为False，则sens默认为'ones_like(outputs)'。默认值：False。如果 `sens_param` 为True，则需要指定sens的值。
             
+    **输入：**
     
-    输入：
     - **(\*inputs)** (Tuple(Tensor...))：shape为 :math:`(N, \ldots)` 的输入tuple。
-        - **(sens)**：反向传播梯度的缩放值。
-          如果网络有单个输出，则sens是tensor。
-          如果网络有多个输出，则sens是tuple(tensor)。
+    - **(sens)**：反向传播梯度的缩放值。如果网络有单个输出，则sens是tensor。如果网络有多个输出，则sens是tuple(tensor)。
 
-    输出：
-        - **forward value**：网络运行的正向结果。
-        - **gradients** (tuple(tensor))：网络反向传播的梯度。
+    **输出：**
+
+    - **forward value** - 网络运行的正向结果。
+    - **gradients** (tuple(tensor)) - 网络反向传播的梯度。
+
+    **支持平台：**
 
-    支持平台：
     ``Ascend`` ``GPU`` ``CPU``
 
-    示例：
+    **样例：**
+
     >>> class Net(nn.Cell):
     ...    def __init__(self)：
     ...        super(Net, self).__init__()

docs/api/api_python/mindspore.train/mindspore.train.SummaryCollector.rst

@@ -1,3 +1,6 @@
+mindspore.train.callback.SummaryCollector
+==========================================
+
 .. py:class:: mindspore.train.callback.SummaryCollector(summary_dir, collect_freq=10, collect_specified_data=None, keep_default_action=True, custom_lineage_data=None, collect_tensor_freq=None, max_file_size=None, export_options=None)
 
     SummaryCollector可以收集一些常用信息。

docs/api/api_python/mindspore.train/mindspore.train.callback.Callback.rst

@@ -1,3 +1,6 @@
+mindspore.train.callback.Callback
+===================================
+
 .. py:class:: mindspore.train.callback.Callback
 
     用于构建回调函数的基类。回调函数是一个上下文管理器，在运行模型时被调用。

docs/api/api_python/mindspore.train/mindspore.train.callback.CheckpointConfig.rst

@@ -1,3 +1,6 @@
+mindspore.train.callback.CheckpointConfig
+==========================================
+
 .. py:class:: mindspore.train.callback.CheckpointConfig(save_checkpoint_steps=1, save_checkpoint_seconds=0, keep_checkpoint_max=5, keep_checkpoint_per_n_minutes=0, integrated_save=True, async_save=False, saved_network=None, append_info=None, enc_key=None, enc_mode='AES-GCM')
 
     保存checkpoint时的配置策略。

docs/api/api_python/mindspore.train/mindspore.train.callback.LearningRateScheduler.rst

@@ -1,3 +1,6 @@
+mindspore.train.callback.LearningRateScheduler
+===============================================
+
 .. py:class:: mindspore.train.callback.LearningRateScheduler(learning_rate_function)
 
     在训练期间更改学习率。

docs/api/api_python/mindspore.train/mindspore.train.callback.LossMonitor.rst

@@ -1,3 +1,6 @@
+mindspore.train.callback.LossMonitor
+=======================================
+
 .. py:class:: mindspore.train.callback.LossMonitor(per_print_times=1)
 
     监控训练的loss。

docs/api/api_python/mindspore.train/mindspore.train.callback.ModelCheckpoint.rst

@@ -1,3 +1,6 @@
+mindspore.train.callback.ModelCheckpoint
+==========================================
+
 .. py:class:: mindspore.train.callback.ModelCheckpoint(prefix='CKP', directory=None, config=None)
 
     checkpoint的回调函数。

docs/api/api_python/mindspore.train/mindspore.train.callback.RunContext.rst

@@ -1,3 +1,6 @@
+mindspore.train.callback.RunContext
+====================================
+
 .. py:class:: mindspore.train.callback.RunContext(original_args)
 
     提供模型的相关信息。

docs/api/api_python/mindspore.train/mindspore.train.callback.TimeMonitor.rst

@@ -1,3 +1,6 @@
+mindspore.train.callback.TimeMonitor
+=====================================
+
 .. py:class:: mindspore.train.callback.TimeMonitor(data_size=None)
 
     监控训练时间。

docs/api/api_python/mindspore.train/mindspore.train.summary.SummaryRecord.rst

@@ -1,3 +1,6 @@
+mindspore.train.summary.SummaryRecord
+=======================================
+
 .. py:class:: mindspore.train.summary.SummaryRecord(log_dir, file_prefix='events', file_suffix='_MS', network=None, max_file_size=None, raise_exception=False, export_options=None)
 
     SummaryRecord用于记录summary数据和lineage数据。
@@ -76,7 +79,6 @@
         ...     with SummaryRecord(log_dir="./summary_dir", file_prefix="xx_", file_suffix="_yy") as summary_record:
         ...         summary_record.add_value('scalar', 'loss', Tensor(0.1))
         
-
     .. py:method:: close()
 
         将所有事件持久化并关闭SummaryRecord。请使用with语句或try…finally语句进行自动关闭。
@@ -90,7 +92,6 @@
         ...     finally:
         ...         summary_record.close()
             
-
     .. py:method:: flush()
 
         将事件文件持久化到磁盘。
@@ -104,7 +105,6 @@
         ...     with SummaryRecord(log_dir="./summary_dir", file_prefix="xx_", file_suffix="_yy") as summary_record:
         ...         summary_record.flush()
         
-
     .. py:method:: log_dir
         :property:
 
@@ -121,7 +121,6 @@
         ...     with SummaryRecord(log_dir="./summary_dir", file_prefix="xx_", file_suffix="_yy") as summary_record:
         ...         log_dir = summary_record.log_dir
         
-
     .. py:method:: record(step, train_network=None, plugin_filter=None)
 
         记录summary。
@@ -150,7 +149,6 @@
         ...
         True
         
-
     .. py:method:: set_mode(mode)
 
         设置训练阶段。不同的训练阶段会影响数据记录。

docs/api/api_python/mindspore/mindspore.build_searched_strategy.rst

@@ -1,7 +1,7 @@
 mindspore.build_searched_strategy
-==================================
+=======================================
 
-.. py:method:: mindspore.build_searched_strategy(strategy_filename)
+.. py:class:: mindspore.build_searched_strategy(strategy_filename)
 
     构建网络中每个参数的策略，用于分布式推理。关于它的使用细节，请参考：`保存和加载模型（HyBrid Parallel模式） <https://www.mindspore.cn/docs/programming_guide/zh-CN/master/save_load_model_hybrid_parallel.html>`_。
 

docs/api/api_python/mindspore/mindspore.set_seed.rst

@@ -6,10 +6,9 @@ mindspore.set_seed
     设置全局种子。
 
     .. note:: 
-
-        全局种子可用于numpy.random,mindspore.common.Initializer,mindspore.ops.composite.random_ops以及mindspore.nn.probability.distribution。
-        如果没有设置全局种子，这些包将会各自使用自己的种子，numpy.random和mindspore.common.Initializer将会随机选择种子值，mindspore.ops.composite.random_ops和mindspore.nn.probability.distribution将会使用零作为种子值。
-        numpy.random.seed()设置的种子仅能被numpy.random使用，而这个API设置的种子也可被numpy.random使用，因此推荐使用这个API设置所有的种子。
+        - 全局种子可用于numpy.random,mindspore.common.Initializer,mindspore.ops.composite.random_ops以及mindspore.nn.probability.distribution。
+        - 如果没有设置全局种子，这些包将会各自使用自己的种子，numpy.random和mindspore.common.Initializer将会随机选择种子值，mindspore.ops.composite.random_ops和mindspore.nn.probability.distribution将会使用零作为种子值。
+        - numpy.random.seed()设置的种子仅能被numpy.random使用，而这个API设置的种子也可被numpy.random使用，因此推荐使用这个API设置所有的种子。
 
     **参数：**
 
@@ -20,11 +19,8 @@ mindspore.set_seed
     - **ValueError** – 种子值非法 (小于0)。
     - **TypeError** – 种子值非整型数。
 
-
     **样例:**
 
-        .. code-block::
-
     >>> import numpy as np
     >>> import mindspore as ms
     >>> import mindspore.ops as ops

docs/api/api_python/nn/mindspore.nn.Adagrad.rst

@@ -41,7 +41,7 @@ mindspore.nn.Adagrad
       - **LearningRateSchedule** - 动态的学习率。在训练过程中，优化器将使用步数（step）作为输入，调用 `LearningRateSchedule` 实例来计算当前学习率。
     
     - **update_slots** (bool) - 如果为True，则更新累加器 :math:`h` 。默认值：True。
-    - **loss_scale** (float) - 梯度缩放系数，必须大于0。如果`loss_scale`是整数，它将被转换为浮点数。通常使用默认值，仅当训练时使用了 `FixedLossScaleManager` ，且 `FixedLossScaleManager` 的 `drop_overflow_update` 属性配置为False时，此值需要与 `FixedLossScaleManager` 中的 `loss_scale` 相同。有关更多详细信息，请参阅class：`mindspore.FixedLossScaleManager` 。默认值：1.0。
+    - **loss_scale** (float) - 梯度缩放系数，必须大于0。如果 `loss_scale` 是整数，它将被转换为浮点数。通常使用默认值，仅当训练时使用了 `FixedLossScaleManager` ，且 `FixedLossScaleManager` 的 `drop_overflow_update` 属性配置为False时，此值需要与 `FixedLossScaleManager` 中的 `loss_scale` 相同。有关更多详细信息，请参阅 :class:`mindspore.FixedLossScaleManager` 。默认值：1.0。
     - **weight_decay** (Union[float, int]) - 要乘以权重的权重衰减值，必须大于等于0.0。默认值：0.0。
 
     **输入：**

docs/api/api_python/nn/mindspore.nn.Adam.rst

@@ -25,7 +25,6 @@ mindspore.nn.Adam
   
         在参数未分组时，优化器配置的 `weight_decay` 应用于名称含有"beta"或"gamma"的网络参数，通过网络参数分组可调整权重衰减策略。分组时，每组网络参数均可配置 `weight_decay` ，若未配置，则该组网络参数使用优化器中配置的 `weight_decay` 。
 
-
     **参数：**
 
     - **params** (Union[list[Parameter], list[dict]]) - 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
@@ -36,7 +35,7 @@ mindspore.nn.Adam
       - **grad_centralization** - 可选。如果键中存在"grad_centralization"，则使用对应的值，该值必须为布尔类型。如果没有，则认为 `grad_centralization` 为False。该参数仅适用于卷积层。
       - **order_params** - 可选。对应值是预期的参数更新顺序。当使用参数分组功能时，通常使用该配置项保持 `parameters` 的顺序以提升性能。如果键中存在"order_params"，则会忽略该组配置中的其他键。"order_params"中的参数必须在某一组 `params` 参数中。
     
-    - **learning_rate (Union[float, Tensor, Iterable, LearningRateSchedule]): 默认值：1e-3。
+    - **learning_rate** (Union[float, Tensor, Iterable, LearningRateSchedule]): 默认值：1e-3。
 
       - **float** - 固定的学习率。必须大于等于零。
       - **int** - 固定的学习率。必须大于等于零。整数类型会被转换为浮点数。
@@ -50,7 +49,7 @@ mindspore.nn.Adam
     - **use_locking** (bool) - 是否对参数更新加锁保护。如果为True，则 `w` 、`m` 和 `v` 的tensor更新将受到锁的保护。如果为False，则结果不可预测。默认值：False。
     - **use_nesterov** (bool) - 是否使用Nesterov Accelerated Gradient (NAG)算法更新梯度。如果为True，使用NAG更新梯度。如果为False，则在不使用NAG的情况下更新梯度。默认值：False。
     - **weight_decay** (float) - 权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。
-    - **loss_scale** (float) - 梯度缩放系数，必须大于0。如果 `loss_scale` 是整数，它将被转换为浮点数。通常使用默认值，仅当训练时使用了 `FixedLossScaleManager` ，且 `FixedLossScaleManager` 的 `drop_overflow_update` 属性配置为False时，此值需要与 `FixedLossScaleManager` 中的 `loss_scale` 相同。有关更多详细信息，请参阅class：`mindspore.FixedLossScaleManager` 。默认值：1.0。
+    - **loss_scale** (float) - 梯度缩放系数，必须大于0。如果 `loss_scale` 是整数，它将被转换为浮点数。通常使用默认值，仅当训练时使用了 `FixedLossScaleManager` ，且 `FixedLossScaleManager` 的 `drop_overflow_update` 属性配置为False时，此值需要与 `FixedLossScaleManager` 中的 `loss_scale` 相同。有关更多详细信息，请参阅 :class:`mindspore.FixedLossScaleManager` 。默认值：1.0。
 
     **输入：**
 

docs/api/api_python/nn/mindspore.nn.Momentum.rst

@@ -27,7 +27,7 @@ mindspore.nn.Momentum
 
     **参数：**
         
-    - **params (Union[list[Parameter], list[dict]]): 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
+    - **params** (Union[list[Parameter], list[dict]]): 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
 
       - ** params** - 必填。当前组别的权重，该值必须是 `Parameter` 列表。
       - ** lr** - 可选。如果键中存在"lr"，则使用对应的值作为学习率。如果没有，则使用优化器中配置的 `learning_rate` 作为学习率。
@@ -35,7 +35,7 @@ mindspore.nn.Momentum
       - ** grad_centralization** - 可选。如果键中存在"grad_centralization"，则使用对应的值，该值必须为布尔类型。如果没有，则认为 `grad_centralization` 为False。该参数仅适用于卷积层。
       - ** order_params** - 可选。对应值是预期的参数更新顺序。当使用参数分组功能时，通常使用该配置项保持 `parameters` 的顺序以提升性能。如果键中存在"order_params"，则会忽略该组配置中的其他键。"order_params"中的参数必须在某一组 `params` 参数中。
     
-    - **learning_rate (Union[float, int, Tensor, Iterable, LearningRateSchedule]):
+    - **learning_rate** (Union[float, int, Tensor, Iterable, LearningRateSchedule]):
 
       - **float** - 固定的学习率。必须大于等于零。
       - **int** - 固定的学习率。必须大于等于零。整数类型会被转换为浮点数。
@@ -45,7 +45,7 @@ mindspore.nn.Momentum
     
     - **momentum** (float) - 浮点数类型的超参，表示移动平均的动量。必须等于或大于0.0。
     - **weight_decay** (int, float) - 权重衰减（L2 penalty）值。必须大于等于0.0。默认值：0.0。
-    - **loss_scale** (float) - 梯度缩放系数，必须大于0。如果 `loss_scale` 是整数，它将被转换为浮点数。通常使用默认值，仅当训练时使用了 `FixedLossScaleManager`，且 `FixedLossScaleManager` 的 `drop_overflow_update` 属性配置为False时，此值需要与 `FixedLossScaleManager` 中的 `loss_scale` 相同。有关更多详细信息，请参阅class：`mindspore.FixedLossScaleManager` 。默认值：1.0。
+    - **loss_scale** (float) - 梯度缩放系数，必须大于0。如果 `loss_scale` 是整数，它将被转换为浮点数。通常使用默认值，仅当训练时使用了 `FixedLossScaleManager`，且 `FixedLossScaleManager` 的 `drop_overflow_update` 属性配置为False时，此值需要与 `FixedLossScaleManager` 中的 `loss_scale` 相同。有关更多详细信息，请参阅 :class:`mindspore.FixedLossScaleManager` 。默认值：1.0。
     - **use_nesterov** (bool) - 是否使用Nesterov Accelerated Gradient (NAG)算法更新梯度。默认值：False。
 
     **输入：**

docs/api/api_python/nn/mindspore.nn.Optimizer.rst

@@ -12,7 +12,7 @@ mindspore.nn.Optimizer
 
     **参数：**
 
-    - **learning_rate (Union[float, int, Tensor, Iterable, LearningRateSchedule]):
+    - **learning_rate** (Union[float, int, Tensor, Iterable, LearningRateSchedule]):
 
       - **float** - 固定的学习率。必须大于等于零。
       - **int** - 固定的学习率。必须大于等于零。整数类型会被转换为浮点数。
@@ -29,7 +29,7 @@ mindspore.nn.Optimizer
       - **order_params** - 可选。对应值是预期的参数更新顺序。当使用参数分组功能时，通常使用该配置项保持 `parameters` 的顺序以提升性能。如果键中存在"order_params"，则会忽略该组配置中的其他键。"order_params"中的参数必须在某一组 `params` 参数中。
 
     - **weight_decay** (Union[float, int]) - 权重衰减的整数或浮点值。必须等于或大于0。如果 `weight_decay` 是整数，它将被转换为浮点数。默认值：0.0。
-    - **loss_scale** (float) - 梯度缩放系数，必须大于0。如果 `loss_scale` 是整数，它将被转换为浮点数。通常使用默认值，仅当训练时使用了 `FixedLossScaleManager`，且 `FixedLossScaleManager `的 `drop_overflow_update` 属性配置为False时，此值需要与 `FixedLossScaleManager` 中的 `loss_scale` 相同。有关更多详细信息，请参阅class：`mindspore.FixedLossScaleManager`。默认值：1.0。
+    - **loss_scale** (float) - 梯度缩放系数，必须大于0。如果 `loss_scale` 是整数，它将被转换为浮点数。通常使用默认值，仅当训练时使用了 `FixedLossScaleManager` ，且 `FixedLossScaleManager` 的 `drop_overflow_update` 属性配置为False时，此值需要与 `FixedLossScaleManager` 中的 `loss_scale` 相同。有关更多详细信息，请参阅 :class:`mindspore.FixedLossScaleManager`。默认值：1.0。
 
     **异常：**
 

docs/api/api_python/nn_probability/mindspore.nn.probability.distribution.Distribution.rst

@@ -34,7 +34,8 @@ mindspore.nn.probability.distribution.Distribution
         重写Cell中的 `construct` 。
 
         .. note:: 
-            支持的函数包括：'prob'、'log_prob'、'cdf', 'log_cdf'、'survival_function'、'log_survival'、'var'、'sd'、'mode'、'mean'、'entropy'、'kl_loss'、'cross_entropy'、'sample'、'get_dist_args'、'get_dist_type'。
+            支持的函数包括：'prob'、'log_prob'、'cdf', 'log_cdf'、'survival_function'、'log_survival'、'var'、
+            'sd'、'mode'、'mean'、'entropy'、'kl_loss'、'cross_entropy'、'sample'、'get_dist_args'、'get_dist_type'。
 
         **参数：**