refine cn doc. (#1187)

* refine doc: pool2d/3d, adaptive_pool2d/3d, grid_sampler, kldiv_loss,
spectral_norm, temporal_shift. test=document_preview

* refine doc: exponential_decay, inverse_time_decay, natural_exp_decay. test=document_preview

* refine doc. test=document_preview

* refine doc for learning_rate_scheduler. test=document_preview

* refine OP. test=document_preview

* fix kldiv_loss. test=document_preview

* fix spectral_norm formula. test=document_preview

doc/fluid/api_cn/layers_cn/adaptive_pool2d_cn.rst

@@ -5,7 +5,9 @@ adaptive_pool2d
 
 .. py:function:: paddle.fluid.layers.adaptive_pool2d(input, pool_size, pool_type='max', require_index=False, name=None)
 
-pooling2d操作根据输入 ``input`` ， ``pool_size`` ， ``pool_type`` 参数计算输出。 输入（X）和输出（Out）采用NCHW格式，其中N是批大小batch size，C是通道数，H是feature(特征)的高度，W是feature（特征）的宽度。 参数 ``pool_size`` 由两个元素构成, 这两个元素分别代表高度和宽度。 输出（Out）的H和W维与 ``pool_size`` 大小相同。
+该OP使用上述输入参数的池化配置，为二维空间自适应池化操作，根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核大小 ``pool_size`` 这些参数得到输出。
+
+输入X和输出Out是NCHW格式，N为批大小，C是通道数，H是特征高度，W是特征宽度。参数 ``pool_size`` 含有两个整型元素, 分别代表高度和宽度上的参数。输出Out的H和W维由 ``pool_size`` 决定，即输出shape为 :math:`\left ( N,C,pool_size[0],pool_size[1] \right )`
 
 
 对于平均adaptive pool2d:
@@ -23,16 +25,16 @@ pooling2d操作根据输入 ``input`` ， ``pool_size`` ， ``pool_type`` 参数
        Output(i ,j) &= \frac{sum(Input[hstart:hend, wstart:wend])}{(hend - hstart) * (wend - wstart)}
 
 参数：
-  - **input** （Variable） - 池化操作的输入张量。 输入张量的格式为NCHW，其中N是batch大小，C是通道数，H是特征的高度，W是特征的宽度。
-  - **pool_size** （int | list | tuple） - 池化核大小。 如果池化核大小是元组或列表，则它必须包含两个整数（pool_size_Height，pool_size_Width）。
+  - **input** （Variable） - 池化操作的输入张量，维度为 :math:`[N, C, H, W]` 的4-D Tensor。 输入张量的格式为NCHW，其中N是batch大小，C是通道数，H是特征的高度，W是特征的宽度，数据类型为float32或float64。
+  - **pool_size** （int|list|tuple） - 池化核大小。 如果池化核大小是元组或列表，则它必须包含两个整数（pool_size_Height，pool_size_Width。若为一个整数，则表示H和W维度上均为该值。
   - **pool_type** （string）- 池化类型，可输入“max”代表max-pooling，或者“avg”代表average-pooling。
-  - **require_index** （bool） - 如果为true，则输出中带有最大池化点所在的索引。 如果pool_type为avg,该项不可被设置为true。
-  - **name** （str | None） - 此层的名称（可选）。 如果设置为None，则将自动命名该层。
+  - **require_index** （bool） - 如果为False，则输出中带有最大池化点所在的索引。 如果pool_type为avg,该项不可被设置为True, 默认False。
+  - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
 
 
-返回： 池化结果
+返回： Variable(Tensor) 自适应池化结果张量
 
-返回类型: Variable
+返回类型：变量(Variable)，数据类型与 ``input`` 一致
 
 
 抛出异常:
@@ -43,6 +45,7 @@ pooling2d操作根据输入 ``input`` ， ``pool_size`` ， ``pool_type`` 参数
 
 .. code-block:: python
 
+    # average adaptive pool2d
     # 假设输入形为[N, C, H, W], `pool_size` 为 [m, n],
     # 输出形为 [N, C, m, n], adaptive pool 将输入的 H 和 W 维度
     # 平均分割为 m * n 个栅格(grid) ，然后为每个栅格进行池化得到输出
@@ -64,6 +67,28 @@ pooling2d操作根据输入 ``input`` ， ``pool_size`` ， ``pool_type`` 参数
                       pool_size=[3, 3],
                       pool_type='avg')
 
+    # max adaptive pool2d
+    # 假设输入形为[N, C, H, W], `pool_size` 为 [m, n],
+    # 输出形为 [N, C, m, n], adaptive pool 将输入的 H 和 W 维度
+    # 平均分割为 m * n 个栅格(grid) ，然后为每个栅格进行池化得到输出
+    # adaptive average pool 进行如下操作
+    #
+    #     for i in range(m):
+    #         for j in range(n):
+    #             hstart = floor(i * H / m)
+    #             hend = ceil((i + 1) * H / m)
+    #             wstart = floor(i * W / n)
+    #             wend = ceil((i + 1) * W / n)
+    #             output[:, :, i, j] = max(input[:, :, hstart: hend, wstart: wend])
+    #
+    import paddle.fluid as fluid
+    data = fluid.layers.data(
+        name='data', shape=[3, 32, 32], dtype='float32')
+    pool_out = fluid.layers.adaptive_pool2d(
+                      input=data,
+                      pool_size=[3, 3],
+                      pool_type='max')
+
 
 
 

doc/fluid/api_cn/layers_cn/adaptive_pool3d_cn.rst

@@ -5,7 +5,9 @@ adaptive_pool3d
 
 .. py:function:: paddle.fluid.layers.adaptive_pool3d(input, pool_size, pool_type='max', require_index=False, name=None)
 
-pooling3d操作根据输入 ``input`` ，``pool_size`` ， ``pool_type`` 参数计算输出。 输入（X）和输出（输出）采用NCDHW格式，其中N是批大小batch size，C是通道数，D是特征(feature)的深度，H是特征的高度，W是特征的宽度。 参数 ``pool_size`` 由三个元素组成。 这三个元素分别代表深度，高度和宽度。输出（Out）的D,H,W维与 ``pool_size`` 相同。
+该OP使用上述输入参数的池化配置，为二维空间自适应池化操作，根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核大小 ``pool_size`` 这些参数得到输出。
+
+输入X和输出Out是NCDHW格式，N为批大小，D是特征深度，C是通道数，H是特征高度，W是特征宽度。参数 ``pool_size`` 含有两个整型元素, 分别代表深度，高度和宽度上的参数。输出Out的D, H和W维由 ``pool_size`` 决定，即输出shape为 :math:`\left ( N,C,pool_size[0],pool_size[1],pool_size[2] \right )`
 
 
 对于平均adaptive pool3d:
@@ -29,16 +31,16 @@ pooling3d操作根据输入 ``input`` ，``pool_size`` ， ``pool_type`` 参数
 
 
 参数：
-  - **input** （Variable） - 池化操作的输入张量。 输入张量的格式为NCDHW，其中N是batch大小，C是通道数，D为特征的深度，H是特征的高度，W是特征的宽度。
-  - **pool_size** （int | list | tuple） - 池化核大小。 如果池化核大小是元组或列表，则它必须包含三个整数（Depth, Height, Width）。
+  - **input** （Variable） - 池化操作的输入张量，维度为 :math:`[N, C, D, H, W]` 的5-D Tensor。 输入张量的格式为NCDHW，其中N是batch大小，C是通道数，D为特征的深度，H是特征的高度，W是特征的宽度，数据类型为float32或float64。
+  - **pool_size** （int|list|tuple） - 池化核大小。 如果池化核大小是元组或列表，则它必须包含三个整数（Depth, Height, Width）。若为一个整数，则表示D, H和W维度上均为该值。
   - **pool_type** （string）- 池化类型，可输入“max”代表max-pooling，或者“avg”代表average-pooling。
-  - **require_index** （bool） - 如果为true，则输出中带有最大池化点所在的索引。 如果pool_type为avg,该项不可被设置为true。
-  - **name** （str | None） - 此层的名称（可选）。 如果设置为None，则将自动命名该层。
+  - **require_index** （bool, 默认False） - 如果为True，则输出中带有最大池化点所在的索引。 如果pool_type为avg,该项不可被设置为True。
+  - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
 
 
-返回： 池化结果
+返回： Variable(Tensor) 自适应池化结果张量
 
-返回类型: Variable
+返回类型：变量(Variable)，数据类型与 ``input`` 一致
 
 
 抛出异常:
@@ -49,6 +51,7 @@ pooling3d操作根据输入 ``input`` ，``pool_size`` ， ``pool_type`` 参数
 
 .. code-block:: python
 
+    # average adaptive pool2d
     # 假设输入形为[N, C, D, H, W], `pool_size` 为 [l, m, n],
     # 输出形为 [N, C, l, m, n], adaptive pool 将输入的D, H 和 W 维度
     # 平均分割为 l * m * n 个栅格(grid) ，然后为每个栅格进行池化得到输出
@@ -76,6 +79,34 @@ pooling3d操作根据输入 ``input`` ，``pool_size`` ， ``pool_type`` 参数
                       pool_size=[3, 3, 3],
                       pool_type='avg')
 
+    # max adaptive pool2d
+    # 假设输入形为[N, C, D, H, W], `pool_size` 为 [l, m, n],
+    # 输出形为 [N, C, l, m, n], adaptive pool 将输入的D, H 和 W 维度
+    # 平均分割为 l * m * n 个栅格(grid) ，然后为每个栅格进行池化得到输出
+    # adaptive average pool 进行如下操作
+    #
+    #     for i in range(l):
+    #         for j in range(m):
+    #             for k in range(n):
+    #                 dstart = floor(i * D / l)
+    #                 dend = ceil((i + 1) * D / l)
+    #                 hstart = floor(j * H / m)
+    #                 hend = ceil((j + 1) * H / m)
+    #                 wstart = floor(k * W / n)
+    #                 wend = ceil((k + 1) * W / n)
+    #                 output[:, :, i, j, k] =
+    #                     avg(input[:, :, dstart:dend, hstart: hend, wstart: wend])
+    #
+    
+    import paddle.fluid as fluid
+
+    data = fluid.layers.data(
+    name='data', shape=[3, 32, 32, 32], dtype='float32')
+    pool_out = fluid.layers.adaptive_pool3d(
+                      input=data,
+                      pool_size=[3, 3, 3],
+                      pool_type='max')
+
 
 
 

doc/fluid/api_cn/layers_cn/exponential_decay_cn.rst

@@ -6,7 +6,10 @@ exponential_decay
 .. py:function:: paddle.fluid.layers.exponential_decay(learning_rate,decay_steps,decay_rate,staircase=False)
 
 在学习率上运用指数衰减。
-训练模型时，推荐在训练过程中降低学习率。每次 ``decay_steps`` 步骤中用 ``decay_rate`` 衰减学习率。
+
+训练模型时，在训练过程中降低学习率。每 ``decay_steps`` 步骤中以 ``decay_rate`` 衰减学习率。
+
+学习率衰减计算方式如下。
 
 .. code-block:: text
 
@@ -16,14 +19,14 @@ exponential_decay
         decayed_learning_rate = learning_rate * decay_rate ^ (global_step / decay_steps)
 
 参数：
-    - **learning_rate** (Variable|float)-初始学习率
-    - **decay_steps** (int)-见以上衰减运算
-    - **decay_rate** (float)-衰减率。见以上衰减运算
-    - **staircase** (Boolean)-若为True,按离散区间衰减学习率。默认：False
+    - **learning_rate** (Variable|float) - 初始学习率，类型可以为学习率变量(Variable)或float型常量。
+    - **decay_steps** (int) - 学习率衰减步长，见以上衰减运算。
+    - **decay_rate** (float) - 学习率衰减率。见以上衰减运算。
+    - **staircase** (bool) - 若为True，按离散区间衰减学习率，即每 ``decay_steps`` 步学习率衰减 ``decay_rate`` 。若为False，则按以上衰减运算持续衰减。默认False。
 
-返回：衰减的学习率
+返回：Variable(Tensor) 随step衰减的学习率变量，维度为 :math:`[1]` 的1-D Tensor。
 
-返回类型：变量（Variable）
+返回类型：变量(Variable)
 
 **代码示例**：
 

doc/fluid/api_cn/layers_cn/grid_sampler_cn.rst

@@ -5,16 +5,15 @@ grid_sampler
 
 .. py:function::  paddle.fluid.layers.grid_sampler(x, grid, name=None)
 
-该操作使用基于flow field网格的双线性插值对输入X进行采样，通常由affine_grid生成。
-
-形状为(N、H、W、2)的网格是由两个形状均为(N、H、W)的坐标(grid_x grid_y)连接而成的。
-
-其中，grid_x是输入数据x的第四个维度(宽度维度)的索引，grid_y是第三维度(高维)的索引，最终得到4个最接近的角点的双线性插值值。
+该OP基于flow field网格的对输入X进行双线性插值采样。网格通常由affine_grid生成, shape为[N, H, W, 2]，是shape为[N, H, W]的采样点张量的(x, y)坐标。
+其中，x坐标是对输入数据X的第四个维度(宽度维度)的索引，y坐标是第三维度(高维度)的索引，最终输出采样值为采样点的4个最接近的角点的双线性插值结果，输出张量的shape为[N, C, H, W]。
 
 step 1：
 
   得到(x, y)网格坐标，缩放到[0,h -1/W-1]
 
+.. code-block:: text
+
   grid_x = 0.5 * (grid[:, :, :, 0] + 1) * (W - 1) grid_y = 0.5 * (grid[:, :, :, 1] + 1) * (H - 1)
 
 step 2：
@@ -51,18 +50,19 @@ step 2：
            + ws * d_e * d_n + es * d_w * d_n
 
 参数：
-  - **x** (Variable): 输入数据，形状为[N, C, H, W]
-  - **grid** (Variable): 输入网格张量，形状为[N, H, W, 2]
-  - **name** (str, default None): 该层的名称
+  - **x** (Variable): 输入张量，维度为 :math:`[N, C, H, W]` 的4-D Tensor，N为批尺寸，C是通道数，H是特征高度，W是特征宽度, 数据类型为float32或float64。
+  - **grid** (Variable): 输入网格数据张量，维度为 :math:`[N, H, W, 2]` 的4-D Tensor，N为批尺寸，C是通道数，H是特征高度，W是特征宽度, 数据类型为float32或float64。
+  - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
+
+返回： Variable(Tensor): 输入X基于输入网格的双线性插值计算结果，维度为 :math:`[N, C, H, W]` 的4-D Tensor
 
-返回： **out** (Variable): 输入X基于输入网格的bilnear插值计算结果，形状为[N, C, H, W]
+返回类型：变量(Variable)，数据类型与 ``x`` 一致
 
 **代码示例：**
 
 .. code-block:: python
 
-    import paddle.fluid as fluid
-
+    # 一般与 affine_grid 组合使用
     x = fluid.layers.data(name='x', shape=[10, 32, 32], dtype='float32')
     theta = fluid.layers.data(name='theta', shape=[2, 3], dtype='float32')
     grid = fluid.layers.affine_grid(theta=theta, out_shape=[3, 10, 32, 32])

doc/fluid/api_cn/layers_cn/inverse_time_decay_cn.rst

@@ -7,7 +7,9 @@ inverse_time_decay
 
 在初始学习率上运用逆时衰减。
 
-训练模型时，最好在训练过程中降低学习率。通过执行该函数，将对初始学习率运用逆向衰减函数。
+训练模型时，最好在训练过程中降低学习率。通过执行该函数，将对初始学习率运用逆时衰减函数。
+
+逆时衰减计算方式如下。
 
 .. code-block:: python
 
@@ -17,14 +19,14 @@ inverse_time_decay
          decayed_learning_rate = learning_rate / (1 + decay_rate * global_step / decay_step)
 
 参数：
-    - **learning_rate** (Variable|float)-初始学习率
-    - **decay_steps** (int)-见以上衰减运算
-    - **decay_rate** (float)-衰减率。见以上衰减运算
-    - **staircase** (Boolean)-若为True，按间隔区间衰减学习率。默认：False
+    - **learning_rate** (Variable|float) - 初始学习率，类型可以为学习率变量(Variable)或float型常量。
+    - **decay_steps** (int) - 学习率衰减步长，见以上衰减运算。
+    - **decay_rate** (float) - 学习率衰减率。见以上衰减运算。
+    - **staircase** (bool) - 若为True，按离散区间衰减学习率，即每 ``decay_steps`` 步多衰减 ``decay_rate`` 倍。若为False，则按以上衰减运算持续衰减。默认False。
 
-返回：衰减的学习率
+返回：Variable(Tensor) 随step衰减的学习率变量，维度为 :math:`[1]` 的1-D Tensor。
 
-返回类型：变量（Variable）
+返回类型：变量(Variable)
 
 **示例代码：**
 

doc/fluid/api_cn/layers_cn/kldiv_loss_cn.rst

@@ -5,7 +5,7 @@ kldiv_loss
 
 .. py:function:: paddle.fluid.layers.kldiv_loss(x, target, reduction='mean', name=None)
 
-此运算符计算输入（x）和输入（Target）之间的Kullback-Leibler发散损失。
+该OP计算输入(X)和输入(Target)之间的Kullback-Leibler散度损失。注意其中输入(X)应为对数概率值，输入(Target)应为概率值。
 
 kL发散损失计算如下：
 
@@ -13,34 +13,49 @@ kL发散损失计算如下：
 
     l(x, y) = y * (log(y) - x)
 
-:math:`x` 为输入（x），:math:`y` 输入（Target）。
+:math:`x` 为输入（X），:math:`y` 输入（Target）。
 
-当 ``reduction``  为 ``none`` 时，输出损失与输入（x）形状相同，各点的损失单独计算，不应用reduction 。
+当 ``reduction``  为 ``none`` 时，输出损失与输入（x）形状相同，各点的损失单独计算，不会对结果做reduction 。
 
-当 ``reduction``  为 ``mean`` 时，输出损失为[1]的形状，损失值为所有损失的平均值。
+当 ``reduction``  为 ``mean`` 时，输出损失为[1]的形状，输出为所有损失的平均值。
 
-当 ``reduction``  为 ``sum`` 时，输出损失为[1]的形状，损失值为所有损失的总和。
+当 ``reduction``  为 ``sum`` 时，输出损失为[1]的形状，输出为所有损失的总和。
 
-当 ``reduction``  为 ``batchmean`` 时，输出损失为[1]的形状，损失值为所有损失的总和除以批量大小。
+当 ``reduction``  为 ``batchmean`` 时，输出损失为[N]的形状，N为批大小，输出为所有损失的总和除以批量大小。
 
 参数:
-    - **x** (Variable) - KL发散损失算子的输入张量。这是一个形状为[N, \*]的张量，其中N是批大小，\*表示任何数量的附加维度
-    - **target** (Variable) - KL发散损失算子的张量。这是一个具有输入（x）形状的张量
+    - **x** (Variable) - KL散度损失算子的输入张量。维度为[N, \*]的多维Tensor，其中N是批大小，\*表示任何数量的附加维度，数据类型为float32或float64。
+    - **target** (Variable) - KL散度损失算子的张量。与输入 ``x`` 的维度和数据类型一致的多维Tensor。
     - **reduction** (Variable)-要应用于输出的reduction类型，可用类型为‘none’ | ‘batchmean’ | ‘mean’ | ‘sum’，‘none’表示无reduction，‘batchmean’ 表示输出的总和除以批大小，‘mean’ 表示所有输出的平均值，‘sum’表示输出的总和。
-    - **name** (str, default None) - 该层的名称
+    - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
 
-返回：KL发散损失
+返回：Variable(Tensor) KL散度损失。
 
-返回类型：kldiv_loss (Variable)
+返回类型：变量(Variable)，数据类型与输入 ``x`` 一致。
 
 **代码示例**：
 
 .. code-block:: python
 
-    import paddle.fluid as fluid
-    x = fluid.layers.data(name='x', shape=[4,2,2], dtype='float32')
+    # 'batchmean' reduction, loss shape 为[N]
+    x = fluid.layers.data(name='x', shape=[4,2,2], dtype='float32') # shape=[-1, 4, 2, 2]
     target = fluid.layers.data(name='target', shape=[4,2,2], dtype='float32')
-    loss = fluid.layers.kldiv_loss(x=x, target=target, reduction='batchmean')
+    loss = fluid.layers.kldiv_loss(x=x, target=target, reduction='batchmean') # shape=[-1]
+
+    # 'mean' reduction, loss shape 为[1]
+    x = fluid.layers.data(name='x', shape=[4,2,2], dtype='float32') # shape=[-1, 4, 2, 2]
+    target = fluid.layers.data(name='target', shape=[4,2,2], dtype='float32')
+    loss = fluid.layers.kldiv_loss(x=x, target=target, reduction='mean') # shape=[1]
+
+    # 'sum' reduction, loss shape 为[1]
+    x = fluid.layers.data(name='x', shape=[4,2,2], dtype='float32') # shape=[-1, 4, 2, 2]
+    target = fluid.layers.data(name='target', shape=[4,2,2], dtype='float32')
+    loss = fluid.layers.kldiv_loss(x=x, target=target, reduction='sum') # shape=[1]
+
+    # 'none' reduction, loss shape 与X相同
+    x = fluid.layers.data(name='x', shape=[4,2,2], dtype='float32') # shape=[-1, 4, 2, 2]
+    target = fluid.layers.data(name='target', shape=[4,2,2], dtype='float32')
+    loss = fluid.layers.kldiv_loss(x=x, target=target, reduction='none') # shape=[-1, 4, 2, 2]
 
 
 

doc/fluid/api_cn/layers_cn/natural_exp_decay_cn.rst

@@ -7,6 +7,10 @@ natural_exp_decay
 
 将自然指数衰减运用到初始学习率上。
 
+训练模型时，在训练过程中降低学习率。 自然指数衰减使用自然指数来计算衰减倍率，每 ``decay_steps`` 步衰减倍率的自然指数幂次项上增加 ``decay_rate`` 。
+
+自然指数学习率衰减计算方式如下。
+
 .. code-block:: python
 
     if not staircase:
@@ -15,12 +19,14 @@ natural_exp_decay
         decayed_learning_rate = learning_rate * exp(- decay_rate * floor(global_step / decay_steps))
 
 参数：
-    - **learning_rate** - 标量float32值或变量。是训练过程中的初始学习率。
-    - **decay_steps** - Python int32数
-    - **decay_rate** - Python float数
-    - **staircase** - Boolean.若设为true，每个decay_steps衰减学习率
+    - **learning_rate** (Variable|float) - 初始学习率，类型可以为学习率变量(Variable)或float型常量。
+    - **decay_steps** (int) - 学习率衰减步长，见以上衰减运算。
+    - **decay_rate** (float) - 学习率衰减率。见以上衰减运算。
+    - **staircase** (bool) - 若为True，按离散区间衰减学习率，即每 ``decay_steps`` 步衰减倍率的自然指数幂次项上增加 ``decay_rate`` 。若为False，则按以上衰减运算持续衰减。默认False。
+
+返回：Variable(Tensor) 随step衰减的学习率变量，维度为 :math:`[1]` 的1-D Tensor。
 
-返回：衰减的学习率
+返回类型：变量(Variable)
 
 **示例代码：**
 

doc/fluid/api_cn/layers_cn/pool2d_cn.rst

@@ -5,11 +5,11 @@ pool2d
 
 .. py:function:: paddle.fluid.layers.pool2d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None, exclusive=True)
 
-pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核大小 ``pool_size`` , 步长 ``pool_stride`` ，填充 ``pool_padding`` 这些参数得到输出。
+该OP使用上述输入参数的池化配置，为二维空间池化操作，根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核大小 ``pool_size`` , 步长 ``pool_stride`` ，填充 ``pool_padding`` 这些参数得到输出。
 
-输入X和输出Out是NCHW格式，N为batch尺寸，C是通道数，H是特征高度，W是特征宽度。
+输入X和输出Out是NCHW格式，N为批大小，C是通道数，H是特征高度，W是特征宽度。
 
-参数（ksize,strides,paddings）含有两个元素。这两个元素分别代表高度和宽度。输入X的大小和输出Out的大小可能不一致。
+参数（ ``ksize``, ``strides``, ``paddings`` ）含有两个整型元素。分别表示高度和宽度上的参数。输入X的大小和输出Out的大小可能不一致。
 
 例如：
 
@@ -56,20 +56,20 @@ pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核
 
 
 参数：
-    - **input** (Variable) - 池化操作的输入张量。输入张量格式为NCHW，N为批尺寸，C是通道数，H是特征高度，W是特征宽度
+    - **input** (Variable) - 池化操作的输入张量。维度为 :math:`[N, C, H, W]` 的4-D Tensor，N为批尺寸，C是通道数，H是特征高度，W是特征宽度, 数据类型为float32或float64。
     - **pool_size** (int|list|tuple)  - 池化核的大小。如果它是一个元组或列表，它必须包含两个整数值， (pool_size_Height, pool_size_Width)。若为一个整数，则它的平方值将作为池化核大小，比如若pool_size=2, 则池化核大小为2x2。
     - **pool_type** (string) - 池化类型，可以是“max”对应max-pooling，“avg”对应average-pooling
-    - **pool_stride** (int|list|tuple)  - 池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。否则它是一个整数的平方值。
-    - **pool_padding** (int|list|tuple) - 填充大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_padding_on_Height, pool_padding_on_Width)。否则它是一个整数的平方值。
-    - **global_pooling** （bool，默认false）- 是否用全局池化。如果global_pooling = true， ``pool_size`` 和 ``pool_padding`` 将被忽略。
-    - **use_cudnn** （bool，默认false）- 只在cudnn核中用，需要下载cudnn
-    - **ceil_mode** （bool，默认false）- 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数
-    - **name** （str|None） - 该层名称（可选）。若设为None，则自动为该层命名。
+    - **pool_stride** (int|list|tuple)  - 池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。若为一个整数，则表示H和W维度上stride均为该值。
+    - **pool_padding** (int|list|tuple) - 填充大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_padding_on_Height, pool_padding_on_Width)。若为一个整数，则表示H和W维度上padding均为该值。
+    - **global_pooling** （bool）- 是否用全局池化。如果global_pooling = True， ``pool_size`` 和 ``pool_padding`` 将被忽略，默认False。
+    - **use_cudnn** （bool）- 只在cudnn核中用，需要下载cudnn，默认True。
+    - **ceil_mode** （bool）- 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数。
+    - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
     - **exclusive** (bool) - 是否在平均池化模式忽略填充值。默认为True。
 
-返回：池化结果
+返回： Variable(Tensor) 池化结果张量
 
-返回类型：变量（Variable）
+返回类型：变量(Variable)，数据类型与 ``input`` 一致
 
 抛出异常：
     - ``ValueError`` - 如果 ``pool_type`` 既不是“max”也不是“avg”
@@ -80,6 +80,7 @@ pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核
 
 .. code-block:: python
 
+    # max pool2d
     import paddle.fluid as fluid
     data = fluid.layers.data(
         name='data', shape=[3, 32, 32], dtype='float32')
@@ -90,7 +91,27 @@ pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核
                   pool_stride=1,
                   global_pooling=False)
 
+    # average pool2d
+    import paddle.fluid as fluid
+    data = fluid.layers.data(
+        name='data', shape=[3, 32, 32], dtype='float32')
+    pool2d = fluid.layers.pool2d(
+                  input=data,
+                  pool_size=2,
+                  pool_type='avg',
+                  pool_stride=1,
+                  global_pooling=False)
 
+    # global average pool2d
+    import paddle.fluid as fluid
+    data = fluid.layers.data(
+        name='data', shape=[3, 32, 32], dtype='float32')
+    pool2d = fluid.layers.pool2d(
+                  input=data,
+                  pool_size=2,
+                  pool_type='avg',
+                  pool_stride=1,
+                  global_pooling=True)
 
 
 

doc/fluid/api_cn/layers_cn/pool3d_cn.rst

@@ -5,9 +5,7 @@ pool3d
 
 .. py:function:: paddle.fluid.layers.pool3d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None, exclusive=True)
 
-函数使用上述输入参数的池化配置，为三维空间添加池化操作
-
-pooling3d操作根据input，pool_type，pool_size，strides和paddings参数计算输出。 输入（X）和输出（输出）采用NCDHW格式，其中N是批量大小，C是通道数，D，H和W分别是特征的深度，高度和宽度。 参数（ksize，strides，paddings）是三个元素。 这三个元素分别代表深度，高度和宽度。 输入（X）大小和输出（Out）大小可能不同。
+该OP使用上述输入参数的池化配置，为三维空间池化操作，根据 ``input`` ，池化类型 ``pool_type`` ，池化核大小 ``pool_size`` ，步长 ``pool_stride`` 和填充 ``pool_padding`` 参数计算输出。 输入（X）和输出（Out）采用NCDHW格式，其中N是批大小，C是通道数，D，H和W分别是特征的深度，高度和宽度。 参数（ ``ksize`` ，``strides`` ，``paddings`` ）含有三个整型元素。 分别代表深度，高度和宽度上的参数。 输入（X）大小和输出（Out）大小可能不同。
 
 
 例如，
@@ -58,25 +56,26 @@ pooling3d操作根据input，pool_type，pool_size，strides和paddings参数计
 
 
 参数：
-    - **input** (Vairable) - 池化运算的输入张量。输入张量的格式为NCDHW, N是批尺寸，C是通道数，D是特征深度，H是特征高度，W是特征宽度。
-    - **pool_size** (int|list|tuple) - 池化窗口的大小。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。
+    - **input** (Vairable) - 池化运算的输入张量, 维度为 :math:`[N, C, D, H, W]` 的5-D Tensor。输入张量的格式为NCDHW, N是批尺寸，C是通道数，D是特征深度，H是特征高度，W是特征宽度，数据类型为float32或float64。
+    - **pool_size** (int|list|tuple) - 池化窗口的大小。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。若为一个整数，则它的立方值将作为池化核大小，比如若pool_size=2, 则池化核大小为2x2x2。
     - **pool_type** (str) - 池化类型， "max" 对应max-pooling, "avg" 对应average-pooling。
-    - **pool_stride** (int|list|tuple) - 池化跨越步长。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。
-    - **pool_padding** (int|list|tuple) - 填充大小。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。
-    - **global_pooling** (bool) - 是否使用全局池化。如果global_pooling = true, ``pool_size`` 和 ``pool_padding`` 将被忽略。
-    - **use_cudnn** (bool) - 是否用cudnn核，只有在cudnn库安装时有效。
+    - **pool_stride** (int|list|tuple) - 池化跨越步长。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。若为一个整数，则表示D, H和W维度上stride均为该值。
+    - **pool_padding** (int|list|tuple) - 填充大小。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。若为一个整数，则表示D, H和W维度上padding均为该值。
+    - **global_pooling** (bool) - 是否使用全局池化。如果global_pooling = true, ``pool_size`` 和 ``pool_padding`` 将被忽略, 默认False。
+    - **use_cudnn** (bool) - 是否用cudnn核，只有在cudnn库安装时有效, 默认True。
     - **ceil_mode** (bool) - 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数。
-    - **name** (str) - 该层名称（可选）。若为空，则自动为该层命名。
+    - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
     - **exclusive** (bool) - 是否在平均池化模式忽略填充值。默认为True。
 
-返回：pool3d层的输出
+返回： Variable(Tensor) 池化结果张量
 
-返回类型：变量（Variable）
+返回类型：变量(Variable)，数据类型与 ``input`` 一致
 
 **代码示例**
 
 .. code-block:: python
 
+    # max pool3d
     import paddle.fluid as fluid
     data = fluid.layers.data(
         name='data', shape=[3, 32, 32, 32], dtype='float32')
@@ -87,6 +86,28 @@ pooling3d操作根据input，pool_type，pool_size，strides和paddings参数计
                       pool_stride=1,
                       global_pooling=False)
 
+    # average pool3d
+    import paddle.fluid as fluid
+    data = fluid.layers.data(
+        name='data', shape=[3, 32, 32, 32], dtype='float32')
+    pool3d = fluid.layers.pool3d(
+                      input=data,
+                      pool_size=2,
+                      pool_type='avg',
+                      pool_stride=1,
+                      global_pooling=False)
+
+    # global average pool3d
+    import paddle.fluid as fluid
+    data = fluid.layers.data(
+        name='data', shape=[3, 32, 32, 32], dtype='float32')
+    pool3d = fluid.layers.pool3d(
+                      input=data,
+                      pool_size=2,
+                      pool_type='avg',
+                      pool_stride=1,
+                      global_pooling=True)
+
 
 
 

doc/fluid/api_cn/layers_cn/spectral_norm_cn.rst

@@ -7,18 +7,18 @@ spectral_norm
 
 **Spectral Normalization Layer**
 
-该层计算了fc、conv1d、conv2d、conv3d层的权重参数的谱正则值，其参数应分别为2-D, 3-D, 4-D, 5-D。计算结果如下。
+该OP用于计算了fc、conv1d、conv2d、conv3d层的权重参数的谱正则值，输入权重参数应分别为2-D, 3-D, 4-D, 5-D张量，输出张量与输入张量shape相同。谱特征值计算方式如下。
 
-步骤1：生成形状为[H]的向量U,以及形状为[W]的向量V,其中H是输入权重的第 ``dim`` 个维度，W是剩余维度的乘积。
+步骤1：生成形状为[H]的向量U,以及形状为[W]的向量V,其中H是输入权重张量的第 ``dim`` 个维度，W是剩余维度的乘积。
 
-步骤2： ``power_iters`` 应该是一个正整数，用U和V迭代计算 ``power_iters`` 轮。
+步骤2： ``power_iters`` 应该是一个正整数，用U和V迭代计算 ``power_iters`` 轮，迭代步骤如下。
 
 .. math::
 
     \mathbf{v} &:= \frac{\mathbf{W}^{T} \mathbf{u}}{\|\mathbf{W}^{T} \mathbf{u}\|_2}\\
     \mathbf{u} &:= \frac{\mathbf{W}^{T} \mathbf{v}}{\|\mathbf{W}^{T} \mathbf{v}\|_2}
 
-步骤3：计算 \sigma(\mathbf{W}) 并权重值归一化。
+步骤3：计算 :math:`\sigma(\mathbf{W})` 并特征值值归一化。
 
 .. math::
     \sigma(\mathbf{W}) &= \mathbf{u}^{T} \mathbf{W} \mathbf{v}\\
@@ -27,22 +27,20 @@ spectral_norm
 可参考: `Spectral Normalization <https://arxiv.org/abs/1802.05957>`_
 
 参数：
-    - **weight** (Variable)-spectral_norm算子的输入权重张量，可以是2-D, 3-D, 4-D, 5-D张量，它是fc、conv1d、conv2d、conv3d层的权重。
-    - **dim** (int)-将输入（weight）重塑为矩阵之前应排列到第一个的维度索引，如果input（weight）是fc层的权重，则应设置为0；如果input（weight）是conv层的权重，则应设置为1，默认为0。
-    - **power_iters** (int)-将用于计算spectral norm的功率迭代次数，默认值1
-    - **eps** (float)-epsilon用于计算规范中的数值稳定性
-    - **name** (str)-此层的名称，可选。
+    - **weight** (Variable) - spectral_norm算子的输入权重张量，可以是2-D, 3-D, 4-D, 5-D Tensor，它是fc、conv1d、conv2d、conv3d层的权重，数据类型为float32或float64。
+    - **dim** (int) - 将输入（weight）重塑为矩阵之前应排列到第一个的维度索引，如果input（weight）是fc层的权重，则应设置为0；如果input（weight）是conv层的权重，则应设置为1，默认为0。
+    - **power_iters** (int) - 将用于计算spectral norm的功率迭代次数，默认值1
+    - **eps** (float) - epsilon用于保证计算规范中的数值稳定性，分母会加上 ``eps`` 防止除零，默认1e-12
+    - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
 
-返回：谱正则化后权重参数的张量变量
+返回：Variable(Tensor) 谱正则化后权重张量，维度与输入 ``weight`` 一致。
 
-返回类型：Variable
+返回类型：变量(Variable)，数据类型与输入 ``weight`` 一致。
 
 **代码示例**：
 
 .. code-block:: python
 
-   import paddle.fluid as fluid
-
    weight = fluid.layers.data(name='weight', shape=[2, 8, 32, 32], append_batch_size=False, dtype='float32')
    x = fluid.layers.spectral_norm(weight=weight, dim=1, power_iters=2)
 

doc/fluid/api_cn/layers_cn/temporal_shift_cn.rst

@@ -4,19 +4,17 @@ temporal_shift
 -------------------------------
 .. py:function:: paddle.fluid.layers.temporal_shift(x, seg_num, shift_ratio=0.25, name=None)
 
-**Temporal Shift Operator**
+该OP用于对输入X做时序通道T上的位移操作，为TSM(Temporal Shift Module)中使用的操作。
 
-此运算符计算输入（x）的时间移位特征。
-
-输入（x）的形状应为[N*T, C, H, W]，N是批大小，T是 ``seg_num`` 指定的时间段号，C是通道号，H和W是特征的高度和宽度。
+输入（X）的形状应为[N*T, C, H, W]，N是批大小，T是 ``seg_num`` 指定的时间段号，C是通道号，H和W是特征的高度和宽度。
 
 时间偏移计算如下：
 
-步骤1：将输入（X）重塑为[N、T、C、H、W]。
+步骤1：将输入（X）reshape为[N, T, C, H, W]。
 
 步骤2：填充0到第二个(T)尺寸的变形结果，填充宽度每边为1，填充结果的形状为[N，T+2，C，H，W]。
 
-步骤3：假设shift_ratio为1/4，切片填充结果如下：
+步骤3：假设 ``shift_ratio`` 为1/4，切片填充结果如下：
 
 .. math::
 
@@ -28,17 +26,17 @@ temporal_shift
 
 步骤4：沿第3(C)维连接三个切片，并将结果重塑为[N*T, C, H, W]。
 
-有关时间移动的详细信息，请参阅文件： `Temporal Shift Module <https://arxiv.org/abs/1811.08383>`_
+有关时序移动的详细信息，请参阅文件： `Temporal Shift Module <https://arxiv.org/abs/1811.08383>`_
 
 参数：
-  - **x**  (Variable) – 时移算符的输入张量。这是一个4维张量，形状为[N*T，C，H，W]。N为批量大小，T为时间段数，C为信道数，H为特征高度，W为特征宽度
+  - **x**  (Variable) – 时移算符的输入张量。维度为 :math:`[N*T，C，H，W]` 的4-D Tensor。N为批量大小，T为时间段数，C为信道数，H为特征高度，W为特征宽度，数据类型为float32或float64。
   - **seg_num**  (int) – 时间段编号，这应该是一个正整数。
-  - **shift_ratio**  (float) – 通道的移位比、通道的第一个 ``shift_ratio`` 部分沿时间维度移动-1，通道的第二个 ``shift_ratio`` 部分沿时间维度移动1。默认值0.25
-  - **name**  (str, default None) – 该层名称
+  - **shift_ratio**  (float) – 通道的移位比、通道的第一个 ``shift_ratio`` 部分沿时间维度移动-1，通道的第二个 ``shift_ratio`` 部分沿时间维度移动1，范围须在[0, 0.5]内。默认值0.25
+  - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
 
-返回：时间移位结果是一个与输入形状和类型相同的张量变量
+返回：Variable(Tensor) 时序位移后的输出张量，维度与输入 ``x`` 一致。
 
-返回类型：out(Variable)
+返回类型：变量(Variable)，数据类型与输入 ``x`` 一致。
 
 抛出异常： ``TypeError`` – seg_num 必须是int类型