improve seq_concat seq_conv e.t api cn doc (#1186)

* improve seq_concat seq_conv e.t api cn doc

* refine doc

* add datatype

doc/fluid/api_cn/layers_cn/get_tensor_from_selected_rows_cn.rst

@@ -5,15 +5,34 @@ get_tensor_from_selected_rows
 
 .. py:function::  paddle.fluid.layers.get_tensor_from_selected_rows(x, name=None)
 
-:code:`Get Tensor From Selected Rows` 用于从选中行（Selected Rows）中获取张量
+该OP从SelectedRows类型的输入中获取向量数据，以LoDTensor的形式输出。
+
+
+::
+
+    例如：
+
+          输入为SelectedRows类型:
+               x.rows = [0, 5, 5, 4, 19]
+               x.height = 20
+               x.value = [[1, 1] [2, 2] [2, 2] [3, 3] [6, 6]]
+
+          输出为LoDTensor：
+               out.shape = [5, 2]
+               out.data = [[1, 1],
+                           [2, 2],
+                           [2, 2],
+                           [3, 3],
+                           [6, 6]]
+
 
 参数：
-  - **x** (Variable) - 输入，类型是SelectedRows
-  - **name** (basestring|None) - 输出的名称
+  - **x** (SelectedRows) - SelectedRows类型的输入，数据类型为float32，float64，int32或int64。
+  - **name** (str) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
 
-返回： 输出类型为LoDTensor
+返回： 从SelectedRows中转化而来的LoDTensor，数据类型和输入一致。
 
-返回类型： out(Variable)
+返回类型： Variable
 
 **代码示例：**
 

doc/fluid/api_cn/layers_cn/sequence_concat_cn.rst

@@ -5,15 +5,37 @@ sequence_concat
 
 .. py:function:: paddle.fluid.layers.sequence_concat(input, name=None)
 
-sequence_concat操作通过序列信息连接LoD张量（Tensor）。例如：X1的LoD = [0,3,7]，X2的LoD = [0,7,9]，结果的LoD为[0，（3 + 7），（7 + 9）]，即[0,10,16]。
+**注意：该OP的输入只能是LoDTensor，如果您需要处理的输入是Tensor类型，请使用concat函数（fluid.layers.** :ref:`cn_api_fluid_layers_concat` **）。**
+
+**该OP仅支持LoDTensor** ，通过LoDTensor的LoD信息将输入的多个LoDTensor进行连接（concat），输出连接后的LoDTensor。
+
+::
+
+    input是由多个LoDTensor组成的list：
+        input = [x1, x2]
+    其中：
+        x1.lod = [[0, 3, 5]]
+        x1.data = [[1], [2], [3], [4], [5]]
+        x1.shape = [5, 1]
+
+        x2.lod = [[0, 2, 4]]
+        x2.data = [[6], [7], [8], [9]]
+        x2.shape = [4, 1]
+    且必须满足：len(x1.lod[0]) == len(x2.lod[0])
+    
+    输出为LoDTensor：
+        out.lod = [[0, 3+2, 5+4]]
+        out.data = [[1], [2], [3], [6], [7], [4], [5], [8], [9]]
+        out.shape = [9, 1]
+
 
 参数:
-        - **input** (list) – 要连接变量的列表
-        - **name** (str|None) – 此层的名称(可选)。如果没有设置，该层将被自动命名。
+        - **input** (list of Variable) – 多个LoDTensor组成的list，要求每个输入LoDTensor的LoD长度必须一致。数据类型为float32，float64或int64。
+        - **name** (str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
 
-返回:     连接好的输出变量。
+返回: 输出连接后的LoDTensor，数据类型和输入一致。
 
-返回类型:   变量（Variable）
+返回类型: Variable
 
 
 **代码示例**

doc/fluid/api_cn/layers_cn/sequence_conv_cn.rst

@@ -3,23 +3,66 @@
 sequence_conv
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.sequence_conv(input, num_filters, filter_size=3, filter_stride=1, padding=None, bias_attr=None, param_attr=None, act=None, name=None)
+.. py:function:: paddle.fluid.layers.sequence_conv(input, num_filters, filter_size=3, filter_stride=1, padding=True, padding_start=None, bias_attr=None, param_attr=None, act=None, name=None)
+
+**注意：该OP的输入只能是LoDTensor，如果您需要处理的输入是Tensor类型，请使用conv2d函数（fluid.layers.** :ref:`cn_api_fluid_layers_conv2d` **）。**
+
+该OP在给定的卷积参数下（如卷积核数目、卷积核大小等），对输入的变长序列（sequence）LoDTensor进行卷积操作。默认情况下，该OP会自适应地在每个输入序列的两端等长地填充全0数据，以确保卷积后的序列输出长度和输入长度一致。支持通过配置 ``padding_start`` 参数来指定序列填充的行为。
+
+**提示：** 参数 ``padding`` 为无用参数，将在未来的版本中被移除。
+
+::
+
+    这里详细介绍数据填充操作的细节：
+    对于一个min-batch为2的变长序列输入，分别包含3个、1个时间步（time_step），
+    假设输入input是一个[4, N]的float类型LoDTensor，为了方便，这里假设N = 2
+        input.data = [[1, 1],
+                      [2, 2],
+                      [3, 3],
+                      [4, 4]]
+        input.lod = [[0, 3, 4]]
+    
+    即输入input总共有4个词，每个词被表示为一个2维向量。
+
+    Case1:
+
+    若 padding_start = -1，filter_size = 3，
+    则两端填充数据的长度分别为：
+        up_pad_len = max(0, -padding_start) = 1
+        down_pad_len = max(0, filter_size + padding_start - 1) = 1
+
+    则以此填充后的输入数据为：
+        data_aftet_padding = [[0, 0, 1, 1, 2, 2],
+                              [1, 1, 2, 2, 3, 3],
+                              [2, 2, 3, 3, 0, 0],
+                              [0, 0, 4, 4, 0, 0]]
+    
+    它将和卷积核矩阵相乘得到最终的输出，假设num_filters = 3：
+        output.data = [[ 0.3234, -0.2334,  0.7433],
+                       [ 0.5646,  0.9464, -0.1223],
+                       [-0.1343,  0.5653,  0.4555],
+                       [ 0.9954, -0.1234, -0.1234]]
+        output.shape = [4, 3]     # 3 = num_filters
+        output.lod = [[0, 3, 4]]  # 保持不变
+
 
-该函数的输入参数中给出了滤波器和步长，通过利用输入以及滤波器和步长的常规配置来为sequence_conv创建操作符。
 
 参数：
-    - **input** (Variable) - (LoD张量）输入X是LoD张量，支持可变的时间量的长度输入序列。该LoDTensor的标记张量是一个维度为（T,N)的矩阵，其中T是mini-batch的总时间步数，N是input_hidden_size
-    - **num_filters** (int) - 滤波器的数量
-    - **filter_size** (int) - 滤波器大小（H和W)
-    - **filter_stride** (int) - 滤波器的步长
-    - **padding** (bool) - 若为真，添加填充
-    - **bias_attr** (ParamAttr|bool|None) - sequence_conv偏离率参数属性。若设为False,输出单元则不加入偏离率。若设为None或ParamAttr的一个属性，sequence_conv将创建一个ParamAttr作为bias_attr。如果未设置bias_attr的初始化函数，则将bias初始化为0.默认:None
-    - **param_attr** (ParamAttr|None) - 可学习参数/sequence_conv的权重参数属性。若设置为None或ParamAttr的一个属性，sequence_conv将创建ParamAttr作为param_attr。
-    若未设置param_attr的初始化函数，则用Xavier初始化参数。默认:None
-
-返回：sequence_conv的输出
-
-返回类型：变量（Variable）
+    - **input** (Variable) - 维度为 :math:`（M, K)` 的二维LoDTensor，仅支持lod_level为1。其中M是mini-batch的总时间步数，K是输入的 ``hidden_size`` 特征维度。数据类型为float32或float64。
+    - **num_filters** (int) - 滤波器的数量。
+    - **filter_size** (int) - 滤波器的高度（H）；不支持指定滤波器宽度（W），宽度固定取值为输入的 ``hidden_size`` 。默认值为3。
+    - **filter_stride** (int) - 滤波器每次移动的步长。目前只支持取值为1，默认为1。
+    - **padding** (bool) - **此参数不起任何作用，将在未来的版本中被移除。** 无论 ``padding`` 取值为False或者True，默认地，该函数会自适应地在每个输入序列的两端等长地填充全0数据，以确保卷积后的输出序列长度和输入长度一致。默认填充是考虑到输入的序列长度可能会小于卷积核大小，这会导致无正确计算卷积输出。填充为0的数据在训练过程中不会被更新。默认为True。
+    - **padding_start** (int) - 表示对输入序列填充时的起始位置，可以为负值。负值表示在每个序列的首端填充 ``|padding_start|`` 个时间步（time_step）的全0数据；正值表示对每个序列跳过前 ``padding_start`` 个时间步的数据。同时在末端填充 :math:`filter\_size + padding\_start - 1` 个时间步的全0数据，以保证卷积输出序列长度和输入长度一致。如果 ``padding_start`` 为None，则在每个序列的两端填充 :math:`\frac{filter\_size}{2}` 个时间步的全0数据；如果 ``padding_start`` 设置为0，则只在序列的末端填充 :math:`filter\_size - 1` 个时间步的全0数据。默认为None。
+    - **bias_attr** (ParamAttr) - 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。
+    - **param_attr** (ParamAttr) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。
+    - **act** (str) – 应用于输出上的激活函数，如tanh、softmax、sigmoid，relu等，支持列表请参考 :ref:`api_guide_activations` ，默认值为None。
+    - **name** (str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
+
+
+返回：和输入序列等长的LoDTensor，数据类型和输入一致，为float32或float64。
+
+返回类型：Variable
 
 **代码示例**
 

doc/fluid/api_cn/layers_cn/sequence_reshape_cn.rst

@@ -5,17 +5,18 @@ sequence_reshape
 
 .. py:function:: paddle.fluid.layers.sequence_reshape(input, new_dim)
 
-Sequence Reshape Layer
-该层重排输入序列。用户设置新维度。每一个序列的的长度通过原始长度、原始维度和新的维度计算得出。以下实例帮助解释该层的功能
+**注意：该OP的输入只能是LoDTensor，如果您需要处理的输入是Tensor类型，请使用reshape函数（fluid.layers.** :ref:`cn_api_fluid_layers_reshape` **）。**
 
-.. code-block:: python
+**该OP仅支持LoDTensor** ，在指定 ``new_dim`` 参数下，通过序列原始长度、和原始shape计算出新的shape，以输出包含新维度（new_dim）下的LoDTensor。目前仅支持1-level LoDTensor，请确保(原长度*原维数)可以除以新的维数，且每个序列没有余数。
+
+::
 
-    x是一个LoDTensor:
-        x.lod  = [[0, 2, 6]]
-        x.data = [[1,  2], [3,  4],
-                [5,  6], [7,  8],
-                [9, 10], [11, 12]]
-        x.dims = [6, 2]
+    input是一个LoDTensor:
+        input.lod  = [[0, 2, 6]]
+        input.data = [[1,  2], [3,  4],
+                      [5,  6], [7,  8],
+                      [9, 10], [11, 12]]
+        input.shape = [6, 2]
     设置 new_dim = 4
     输出为LoDTensor:
         out.lod  = [[0, 1, 3]]
@@ -23,17 +24,17 @@ Sequence Reshape Layer
         out.data = [[1,  2,  3,  4],
                     [5,  6,  7,  8],
                     [9, 10, 11, 12]]
-        out.dims = [3, 4]
+        out.shape = [3, 4]
+
 
-目前仅提供1-level LoDTensor，请确保(原长度*原维数)可以除以新的维数，每个序列没有余数。
 
 参数：
-    - **input** (Variable)-一个2-D LoDTensor,模型为[N,M]，维度为M
-    - **new_dim** (int)-新维度，输入LoDTensor重新塑造后的新维度
+    - **input** (Variable) - 维度为 :math:`[M, K]` 的二维LoDTensor，且仅支持lod_level为1。数据类型为int32，int64，float32或float64。
+    - **new_dim** (int)- 指定reshape后的新维度，即对输入LoDTensor重新reshape后的新维度。
 
-返回：根据新维度重新塑造的LoDTensor
+返回：根据新维度重新reshape后的LoDTensor，数据类型和输入一致。
 
-返回类型：变量（Variable）
+返回类型：Variable
 
 **代码示例**：
 

doc/fluid/api_cn/layers_cn/sequence_reverse_cn.rst

@@ -5,34 +5,36 @@ sequence_reverse
 
 .. py:function:: paddle.fluid.layers.sequence_reverse(x, name=None)
 
+**注意：该OP的输入只能是LoDTensor，如果您需要处理的输入是Tensor类型，请使用reverse函数（fluid.layers.** :ref:`cn_api_fluid_layers_reverse` **）。**
 
-在第0维上将输入 ``x`` 的各序列倒序。
+**该OP仅支持LoDTensor** ，对于输入的LoDTensor，在每个序列（sequence）上进行反转。目前仅支持对LoD层次(LoD level)为1的LoDTensor进行反转。该OP在构建反向 :ref:`cn_api_fluid_layers_DynamicRNN` 网络时十分有用。
 
 ::
 
-    假设 ``x`` 是一个形为 (5,4) 的LoDTensor， lod信息为 [[0, 2, 5]]，其中，
+    输入x是一个LoDTensor:
+        x.lod  = [[0, 2, 5]]
+        x.data = [[1,  2,  3,  4],
+                  [5,  6,  7,  8],
+                  [9, 10, 11, 12],
+                  [13,14, 15, 16],
+                  [17,18, 19, 20]]
+        x.shape = [5, 4]
+
+    输出out与x具有同样的shape和LoD信息：
+        out.lod  = [[0, 2, 5]]
+        out.data = [[5,  6,  7,  8],
+                    [1,  2,  3,  4],
+                    [17,18, 19, 20],
+                    [13,14, 15, 16],
+                    [9, 10, 11, 12]]
+        out.shape = [5, 4]
 
 
-    X.data() = [ [1, 2, 3, 4], [5, 6, 7, 8], # 索引为0，长度为2的序列
-
-                 [9, 10, 11, 12], [13, 14, 15, 16], [17, 18, 19, 20] # 索引为1长度为3的序列
-
-输出 ``Y`` 与 ``x`` 具有同样的维数和LoD信息。 于是有：
-
-::
-
-    Y.data() = [ [5, 6, 7, 8], [1, 2, 3, 4], # 索引为0，长度为2的逆序列
-                 [17, 18, 19, 20], [13, 14, 15, 16], [9, 10, 11, 12] # 索引为1，长度为3的逆序列
-
-该运算在建立反dynamic RNN 网络中十分有用。
-
-目前仅支持LoD层次(LoD level)为1的张量倒序。
-
 参数:
-  - **x** (Variable) – 输入张量
-  - **name** (basestring|None) – 输出变量的命名
+  - **x** (Variable) – 输入是LoD level为1的LoDTensor。目前仅支持对LoD层次(LoD level)为1的LoDTensor进行反转。数据类型为float32，float64，int8，int32或int64。
+  - **name** (str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
 
-返回：输出LoD张量
+返回：输出在每个序列上反转后的LoDTensor，数据类型和输入类型一致。
 
 返回类型：Variable