polish api_cn for 1.6 (#1311)

* polish api_cn, test=document_preview

* update api_cn

* change description for op

* add noam_decay

* update api_cn

* update api_cn doc

doc/fluid/api_cn/initializer_cn/XavierInitializer_cn.rst

@@ -22,9 +22,9 @@ XavierInitializer
     x = \sqrt{\frac{2.0}{fan\_in+fan\_out}}
 
 参数：
-    - **uniform** (bool) - 是否用均匀分布或者正态分布
-    - **fan_in** (float) - 用于Xavier初始化的fan_in。如果为None，fan_in沿伸自变量
-    - **fan_out** (float) - 用于Xavier初始化的fan_out。如果为None，fan_out沿伸自变量
+    - **uniform** (bool) - 是否用均匀分布，默认为True。如果为False，则使用正态分布。
+    - **fan_in** (float) - 当前网络层的输入神经元个数。如果为None，则从变量中推断，默认为None。
+    - **fan_out** (float) - 当前网络层的输出神经元个数。如果为None，则从变量中推断，默认为None。
     - **seed** (int) - 随机种子
 
 .. note::

doc/fluid/api_cn/layers_cn/acos_cn.rst

@@ -11,16 +11,23 @@ arccosine激活函数。
     out = cos^{-1}(x)
 
 参数:
-    - **x** - acos算子的输入
+    - **x(Variable)** - acos的输入Tensor，数据类型为 float32 或 float64
+    - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
+返回：  `acos` 的输出Tensor，数据类型与 `x` 相同。
+
+返回类型： Variable
+
 
-返回：        acos算子的输出。
 
 **代码示例**：
 
 .. code-block:: python
 
         import paddle.fluid as fluid
-        data = fluid.layers.data(name="input", shape=[32, 784])
+        data = fluid.layers.data(name="input", shape=[4])
+        # if data is [-0.8183,  0.4912, -0.6444,  0.0371]
         result = fluid.layers.acos(data)
+        # result is [2.5293, 1.0573, 2.2711, 1.5336]
+
 
 

doc/fluid/api_cn/layers_cn/asin_cn.rst

@@ -10,18 +10,24 @@ arcsine激活函数。
 .. math::
     out = sin^{-1}(x)
 
+
 参数:
-    - **x** - asin算子的输入
+    - **x(Variable)** - asin的输入Tensor，数据类型为 float32 或 float64
+    - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
+
+返回：  `asin` 的输出Tensor，数据类型与 `x` 相同。
 
-返回：        asin算子的输出。
+返回类型： Variable
 
 **代码示例**：
 
 .. code-block:: python
 
         import paddle.fluid as fluid
-        data = fluid.layers.data(name="input", shape=[32, 784])
+        data = fluid.layers.data(name="input", shape=[4])
+        # if data is [-0.8183,  0.4912, -0.6444,  0.0371]
         result = fluid.layers.asin(data)
+        # result is [-0.9585,  0.5135, -0.7003,  0.0372]
 
 
 

doc/fluid/api_cn/layers_cn/atan_cn.rst

@@ -11,17 +11,22 @@ arctanh激活函数。
     out = tanh^{-1}(x)
 
 参数:
-    - **x** - atan算子的输入
+    - **x(Variable)** - atan的输入Tensor，数据类型为 float32 或 float64
+    - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
 
-返回：       atan算子的输出。
+返回：  `atan` 的输出Tensor，数据类型与 `x` 相同。
+
+返回类型： Variable
 
 **代码示例**：
 
 .. code-block:: python
 
         import paddle.fluid as fluid
-        data = fluid.layers.data(name="input", shape=[32, 784])
+        data = fluid.layers.data(name="input", shape=[4])
+        # if data is [-0.8183,  0.4912, -0.6444,  0.0371]
         result = fluid.layers.atan(data)
+        # result is [-0.6858,  0.4566, -0.5724,  0.0371]
 
 
 

doc/fluid/api_cn/layers_cn/multiclass_nms_cn.rst

@@ -7,36 +7,55 @@ multiclass_nms
 
 **多分类NMS**
 
-该运算用于对边界框（bounding box）和评分进行多类非极大值抑制（NMS）。
+该OP用于对边界框（bounding box）和评分（scores）执行多类非极大值抑制（NMS）。
 
-在NMS中，如果提供 ``score_threshold`` 阈值，则此算子贪婪地选择具有高于 ``score_threshold`` 的高分数的检测边界框（bounding box）的子集，然后如果nms_top_k大于-1，则选择最大的nms_top_k置信度分数。 接着，该算子基于 ``nms_threshold`` 和 ``nms_eta`` 参数，通过自适应阈值NMS移去与已经选择的框具有高IOU（intersection over union）重叠的框。
+在NMS中，如果提供 ``score_threshold`` 阈值，则此OP贪心地选择所有得分（scores）高于 ``score_threshold`` 的检测边界框（bounding box）的子集，如果nms_top_k大于-1，则选择最大的nms_top_k置信度分数。 接着，该OP依据 adaptive nms（基于 ``nms_threshold`` 和 ``nms_eta``），删除与已选择的框IOU(交并比)高于nms_threshold 的重叠框。
+
+在NMS步骤后，如果keep_top_k大于-1，则每个图像最多保留keep_top_k个框（bounding box）。
+
+计算示例：
+    .. code-block:: text
+
+        如果:
+            box1.data = (2.0, 3.0, 7.0, 5.0)  数据格式为 (xmin, ymin, xmax, ymax)
+            box1.scores = (0.7, 0.2, 0.4)   其中 (label0.score=0.7, label1.score=0.2, label2.cores=0.4)
+            box2.data = (3.0, 4.0, 8.0, 5.0)
+            box2.score = (0.3, 0.3, 0.1)
+            nms_threshold = 0.3
+            background_label = 0
+            score_threshold = 0
+        则:
+            iou = 4/11 > 0.3
+            out.data = [[1, 0.3, 3.0, 4.0, 8.0, 5.0],    
+                         [2, 0.4, 2.0, 3.0, 7.0, 5.0]]
+                         
+            输出数据格式为 (label, confidence, xmin, ymin, xmax, ymax)
 
-在NMS步骤后，如果keep_top_k大于-1，则每个图像最多保留keep_top_k个总bbox数。
 
 
 参数：
-    - **bboxes**  (Variable) – 支持两种类型的bbox（bounding box）:
+    - **bboxes**  (Variable) – 支持两种类型的边界框（bounding box）:
 
-      1. （Tensor）具有形[N，M，4]或[8 16 24 32]的3-D张量表示M个边界bbox的预测位置， N是批大小batch size。当边界框(bounding box)大小等于4时，每个边界框有四个坐标值，布局为[xmin，ymin，xmax，ymax]。
-      2. （LoDTensor）形状为[M，C，4] M的三维张量是边界框的数量，C是种类数量
+      1. （Tensor）形为[N，M，4 或 8、16、24、32]的3-D张量，表示将预测M个边界框的预测位置， N是批大小（batch size）。当边界框(bounding box)大小等于4时，每个边界框有四个坐标值，布局为[xmin，ymin，xmax，ymax]。数据类型为float32或float64。
+      2. （LoDTensor）形状为[M，C，4] M是边界框的个数，C是类别个数。数据类型为float32或float64
 
     - **scores**  (Variable) – 支持两种类型的分数：
 
-      1. （tensor）具有形状[N，C，M]的3-D张量表示预测的置信度。 N是批量大小 batch size，C是种类数目，M是边界框bounding box的数量。对于每个类别，存在对应于M个边界框的总M个分数。请注意，M等于bboxes的第二维。
-      2. （LoDTensor）具有形状[M，C]的2-D LoDTensor。 M是bbox的数量，C是种类数目。在这种情况下，输入bboxes应该是形为[M，C，4]的第二种情况。
+      1. （Tensor）具有形状[N，C，M]的3-D张量表示预测的置信度。 N是批量大小 batch size，C是种类数目，M是边界框bounding box的数量。对于每个类别，存在对应于M个边界框的总M个分数。请注意，M等于bboxes的第二维。数据类型为float32或float64。
+      2. （LoDTensor）具有形状[M，C]的2-D LoDTensor。 M是bbox的数量，C是种类数目。在这种情况下，输入bboxes应该是形为[M，C，4]的第二种情况。数据类型为float32或float64。
 
-    - **background_label**  (int) – 背景标签（类别）的索引，背景标签（类别）将被忽略。如果设置为-1，则将考虑所有类别。默认值：0
+    - **background_label**  (int) – 背景标签（类别）的索引，如果设置为 0 ，则忽略背景标签（类别）。如果设置为 -1 ，则考虑所有类别。默认值：0
     - **score_threshold**  (float) – 过滤掉低置信度分数的边界框的阈值。如果没有提供，请考虑所有边界框。
-    - **nms_top_k**  (int) – 根据通过score_threshold的过滤后而得的检测(detection)的置信度，所需要保留的最大检测数。
-    - **nms_threshold**  (float) – 在NMS中使用的阈值。默认值：0.3 。
-    - **nms_eta**  (float) – 在NMS中使用的阈值。默认值：1.0 。
+    - **nms_top_k**  (int) – 基于 score_threshold 的过滤检测后，根据置信度保留的最大检测次数。
+    - **nms_threshold**  (float) – 在NMS中用于剔除检测框IOU的阈值，默认值：0.3 。
+    - **nms_eta**  (float) – 在NMS中用于调整 nms_threshold 的参数，设为1时表示nms_threshold不变。默认值：1.0 。
     - **keep_top_k**  (int) – NMS步骤后每个图像要保留的总bbox数。 -1表示在NMS步骤之后保留所有bbox。
     - **normalized**  (bool) –  检测是否已经经过正则化。默认值：True 。
-    - **name**  (str) – 多类nms op(此op)的名称，用于自定义op在网络中的命名。默认值：None 。
+    - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
 
 返回：形为[No，6]的2-D LoDTensor，表示检测(detections)结果。每行有6个值：[标签label，置信度confidence，xmin，ymin，xmax，ymax]。或形为[No，10]的2-D LoDTensor，用来表示检测结果。 每行有10个值：[标签label，置信度confidence，x1，y1，x2，y2，x3，y3，x4，y4]。 No是检测的总数。 如果对所有图像都没有检测到的box，则lod将设置为{1}，而Out仅包含一个值-1。 （1.3版本之后，当未检测到box时，lod从{0}更改为{1}）
 
-返回类型：Out
+返回类型：Variable，数据类型与输入一致。
 
 **代码示例**
 

doc/fluid/api_cn/layers_cn/noam_decay_cn.rst

@@ -5,7 +5,9 @@ noam_decay
 
 .. py:function:: paddle.fluid.layers.noam_decay(d_model,warmup_steps)
 
-Noam衰减方法。noam衰减的numpy实现如下。
+Noam衰减方法
+
+noam衰减的numpy实现如下：
 
 .. code-block:: python
 
@@ -23,11 +25,13 @@ Noam衰减方法。noam衰减的numpy实现如下。
 请参照 `attention is all you need <https://arxiv.org/pdf/1706.03762.pdf>`_
 
 参数：
-    - **d_model** (Variable)-模型的输入和输出维度
-    - **warmup_steps** (Variable)-超参数
+    - **d_model** (Variable|int) - 模型的输入、输出向量特征维度。类型可设置为标量Tensor，或int值。
+    - **warmup_steps** (Variable|int) - 预热步数，类型可设置为标量Tensor，或int值。
 
 返回：衰减的学习率
 
+返回类型： Variable
+
 **代码示例**：
 
 .. code-block:: python

doc/fluid/api_cn/layers_cn/piecewise_decay_cn.rst

@@ -21,8 +21,8 @@ piecewise_decay
         learning_rate = 0.1
 
 参数：
-    - **boundaries** -一列代表步数的数字
-    - **values** -一列学习率的值，从不同的步边界中挑选
+    - **boundaries(list)** - 代表步数的数字
+    - **values(list)** - 学习率的值，不同的步边界中的学习率值
 
 返回：衰减的学习率
 

doc/fluid/api_cn/layers_cn/polynomial_decay_cn.rst

@@ -17,11 +17,11 @@ polynomial_decay
             (1 - global_step / decay_steps) ^ power + end_learning_rate
 
 参数：
-    - **learning_rate** (Variable|float32)-标量float32值或变量。是训练过程中的初始学习率。
-    - **decay_steps** (int32)-Python int32数
-    - **end_learning_rate** (float)-Python float数
-    - **power** (float)-Python float数
-    - **cycle** (bool)-若设为true，每decay_steps衰减学习率
+    - **learning_rate** (Variable|float) - 训练过程中的初始学习率，数据类型为float的常数或变量。
+    - **decay_steps** (int) - 衰减步数
+    - **end_learning_rate** (float) - 训练过程的最终学习率
+    - **power** (float) - 多项式衰减系数
+    - **cycle** (bool) - step 超出 decay_steps 后是否继续循环，默认为False
 
 返回：衰减的学习率
 

doc/fluid/api_cn/layers_cn/yolo_box_cn.rst

@@ -6,9 +6,9 @@ yolo_box
 .. py:function:: paddle.fluid.layers.yolo_box(x, img_size, anchors, class_num, conf_thresh, downsample_ratio, name=None)
 
 
-该运算符从YOLOv3网络的输出生成YOLO检测框。
+该运算符基于YOLOv3网络的输出结果，生成YOLO检测框。
 
-先前网络的输出形状为[N，C，H，W]，而H和W应相同，用来指定网格大小。对每个网格点预测给定的数目的框，这个数目记为S，由anchor的数量指定。 在第二维（通道维度）中，C应该等于S *（5 + class_num），class_num是源数据集中对象类别数目（例如coco数据集中的80），此外第二个（通道）维度中还有4个框位置坐标x，y，w，h，以及anchor box的one-hot key的置信度得分。
+连接 yolo_box 网络的输出形状应为[N，C，H，W]，其中 H 和 W 相同，用来指定网格大小。对每个网格点预测给定的数目的框，这个数目记为 S ，由 anchor 的数量指定。 在第二维（通道维度）中，C应该等于S *（5 + class_num），class_num是源数据集中对象类别数目（例如coco数据集中的80），此外第二个（通道）维度中还有4个框位置坐标x，y，w，h，以及anchor box的one-hot key的置信度得分。
 
 假设4个位置坐标是 :math:`t_x` ，:math:`t_y` ，:math:`t_w` ， :math:`t_h`
 ，则框的预测算法为：
@@ -31,15 +31,17 @@ yolo_box
 
 
 参数：
-    - **x** （Variable） -  YoloBox算子的输入张量是一个4-D张量，形状为[N，C，H，W]。第二维（C）存储每个anchor box位置坐标，每个anchor box的置信度分数和one hot key。通常，X应该是YOLOv3网络的输出
-    - **img_size** （Variable） -  YoloBox算子的图像大小张量，这是一个形状为[N，2]的二维张量。该张量保持每个输入图像的高度和宽度，用于对输出图像按输入图像比例调整输出框的大小
+    - **x** （Variable） -  YoloBox的输入张量是一个4-D张量，形状为[N，C，H，W]。第二维（C）存储每个anchor box位置坐标，每个anchor box的置信度分数和one hot key。通常，X应该是YOLOv3网络的输出。数据类型为float32或float64
+    - **img_size** （Variable） -  YoloBox的图像大小张量，这是一个形状为[N，2]的二维张量。该张量保持每个输入图像的高度和宽度，用于对输出图像按输入图像比例调整输出框的大小。数据类型为int32。
     - **anchors** （list | tuple） - anchor的宽度和高度，它将逐对解析
     - **class_num** （int） - 要预测的类数
     - **conf_thresh** （float） - 检测框的置信度得分阈值。置信度得分低于阈值的框应该被忽略
     - **downsample_ratio** （int） - 从网络输入到YoloBox操作输入的下采样率，因此应依次为第一个，第二个和第三个YoloBox运算设置该值为32,16,8
-    - **name** （string） -  yolo box层的名称。默认None。
+    - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
 
-返回: 具有形状[N，M，4]的三维张量，框的坐标；以及具有形状[N，M，class_num]的三维张量，框的分类得分；
+返回: 
+     1. 框的坐标，形为[N，M，4]的三维张量
+     2. 框的分类得分， 形为 [N，M，class_num]的三维张量
 
 返回类型:   变量（Variable）
 

doc/fluid/api_cn/layers_cn/yolov3_loss_cn.rst

@@ -5,9 +5,9 @@ yolov3_loss
 
 .. py:function:: paddle.fluid.layers.yolov3_loss(x, gt_box, gt_label, anchors, anchor_mask, class_num, ignore_thresh, downsample_ratio, gt_score=None, use_label_smooth=True, name=None)
 
-该运算通过给定的预测结果和真实框生成yolov3损失。
+该运算通过给定的预测结果和真实框计算yolov3损失。
 
-之前的网络的输出形状为[N，C，H，W]，而H和W应该相同，用来指定网格(grid)大小。每个网格点预测给定的数目的边界框(bounding boxes)，这个给定的数字由每个尺度中 ``anchors`` 簇的个数指定，我们将它记为S。在第二维（表示通道的维度）中，C的值应为S *（class_num + 5），class_num是源数据集的对象种类数（如coco中为80），另外，除了存储4个边界框位置坐标x，y，w，h，还包括边界框以及每个anchor框的one-hot关键字的置信度得分。
+yolov3 loss前的网络输出形状为[N，C，H，W]，H和W应该相同，用来指定网格(grid)大小。每个网格点预测S个边界框(bounding boxes)，S由每个尺度中 ``anchors`` 簇的个数指定。在第二维（表示通道的维度）中，C的值应为S *（class_num + 5），class_num是源数据集的对象种类数（如coco中为80），另外，除了存储4个边界框位置坐标x，y，w，h，还包括边界框以及每个anchor框的one-hot关键字的置信度得分。
 
 假设有四个表征位置的坐标为 :math:`t_x, t_y, t_w, t_h` ,那么边界框的预测将会如下定义:
 
@@ -25,13 +25,13 @@ yolov3_loss
          $$
 
 在上面的等式中， :math:`c_x, c_y` 是当前网格的左上角, :math:`p_w, p_h` 由anchors指定。
-至于置信度得分，它是anchor框和真实框之间的IoU的逻辑回归值，anchor框的得分最高为1，此时该anchor框对应着最大IoU。
+置信度得分是anchor框和真实框之间的IoU的逻辑回归值，anchor框的得分最高为1，此时该anchor框对应着最大IoU。
 如果anchor框之间的IoU大于忽略阀值ignore_thresh，则该anchor框的置信度评分损失将会被忽略。
          
 因此，yolov3损失包括三个主要部分，框位置损失，目标性损失，分类损失。L1损失用于
 框坐标（w，h），同时，sigmoid交叉熵损失用于框坐标（x，y），目标性损失和分类损失。
          
-每个真实框在所有anchor中找到最匹配的anchor，预测各anchor框都将会产生所有三种损失的计算，但是没有匹配GT box(ground truth box真实框)的anchor的预测只会产生目标性损失。
+每个真实框将在所有anchor中找到最匹配的anchor，对该anchor的预测将会计算全部（三种）损失，但是没有匹配GT box(ground truth box真实框)的anchor的预测只会产生目标性损失。
 
 为了权衡大框(box)和小(box)之间的框坐标损失，框坐标损失将与比例权重相乘而得。即：
 
@@ -46,29 +46,29 @@ yolov3_loss
          $$
 
 
-当 ``use_label_smooth`` 设置为 ``True`` 时，在计算分类损失时将平滑分类目标，将正样本的目标平滑到1.0-1.0 / class_num，并将负样本的目标平滑到1.0 / class_num。
+当 ``use_label_smooth`` 为 ``True`` 时，在计算分类损失时将平滑分类目标，将正样本的目标平滑到1.0-1.0 / class_num，并将负样本的目标平滑到1.0 / class_num。
 
-如果给出了 ``GTScore`` 表示真实框的mixup得分，那么真实框所产生的所有损失将乘以其混合得分。
+``GTScore`` （如果存在）表示真实框的mixup得分，那么真实框所产生的所有损失需要乘上GTScore。
 
 
 
 参数：
-    - **x**  (Variable) – YOLOv3损失运算的输入张量，这是一个形状为[N，C，H，W]的四维张量。H和W应该相同，第二维（C）存储框的位置信息，以及每个anchor box的置信度得分和one-hot分类
-    - **gt_box**  (Variable) – 真实框，应该是[N，B，4]的形状。第三维用来承载x、y、w、h，其中 x, y是真实框的中心坐标，w, h是框的宽度和高度，且x、y、w、h将除以输入图片的尺寸，缩放到[0,1]区间内。 N是batch size，B是图像中所含有的的最多的box数目
-    - **gt_label**  (Variable) – 真实框的类id，应该形为[N，B]。
+    - **x**  (Variable) – YOLOv3损失运算的输入张量，这是一个形状为[N，C，H，W]的四维Tensor。H和W应该相同，第二维（C）存储框的位置信息，以及每个anchor box的置信度得分和one-hot分类。数据类型为float32或float64。
+    - **gt_box**  (Variable) – 真实框，应该是[N，B，4]的形状。第三维用来承载x、y、w、h，其中 x, y是真实框的中心坐标，w, h是框的宽度和高度，且x、y、w、h将除以输入图片的尺寸，缩放到[0,1]区间内。 N是batch size，B是图像中所含有的的最多的box数目。数据类型为float32或float64。
+    - **gt_label**  (Variable) – 真实框的类id，应该形为[N，B]。数据类型为int32。
     - **anchors**  (list|tuple) – 指定anchor框的宽度和高度，它们将逐对进行解析
-    - **anchor_mask**  (list|tuple) – 当前YOLOv3损失计算中使用的anchor的mask索引
-    - **class_num**  (int) – 要预测的类数
+    - **anchor_mask**  (list|tuple) – 当前YOLOv3损失计算中使用anchor的mask索引
+    - **class_num**  (int) – 要预测的类别数
     - **ignore_thresh**  (float) – 一定条件下忽略某框置信度损失的忽略阈值
-    - **downsample_ratio**  (int) – 从网络输入到YOLOv3 loss输入的下采样率，因此应为第一，第二和第三个YOLOv3损失运算设置32,16,8
-    - **name** (string) – yolov3损失层的命名
-    - **gt_score** （Variable） - 真实框的混合得分，形为[N，B]。 默认None。
+    - **downsample_ratio**  (int) – 网络输入到YOLOv3 loss输入的下采样率，因此第一，第二和第三个 loss 的下采样率应分别为32,16,8
+    - **gt_score** （Variable） - 真实框的混合得分，形为[N，B]。 默认None。数据类型为float32或float64。
     - **use_label_smooth** (bool） - 是否使用平滑标签。 默认为True
+    - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
 
 
-返回: 具有形状[N]的1-D张量，yolov3损失的值
+返回: yolov3损失的值，具有形状[N]的1-D张量。
 
-返回类型:   变量（Variable）
+返回类型:   变量（Variable），数据类型与input一致。
 
 抛出异常:
     - ``TypeError``  – yolov3_loss的输入x必须是Variable