update documents (#1204)

* refine api comments

* refine api comments

* update docs

* update docs

doc/fluid/api_cn/io_cn/xmap_readers_cn.rst

@@ -5,15 +5,50 @@ xmap_readers
 
 .. py:function:: paddle.fluid.io.xmap_readers(mapper, reader, process_num, buffer_size, order=False)
 
-通过多线程方式，通过用户自定义的映射器mapper来映射reader返回的样本（到输出队列）。
+多线程下，使用自定义映射器 reader 返回样本到输出队列。
 
 参数：
-    - **mapper** （callable） - 一种映射reader数据的函数。
-    - **reader** （callable） - 产生数据的reader。
-    - **process_num** （int） - 用于处理样本的线程数目。
-    - **buffer_size** （int） - 存有待读取数据的队列的大小。
-    - **order** （bool） - 是否保持原始reader的数据顺序。 默认为False。
+    - **mapper** （callable）: 映射 reader 数据的函数。
+    - **reader** （callable）: 产生数据的 reader。
+    - **process_num** （int）: 处理样本的线程数。
+    - **buffer_size** （int）: 数据缓冲队列大小。
+    - **order** （bool）: 是否保持原始 reader 数据顺序，默认为 False。
 
-返回：一个将原数据进行映射后的decorated reader。
+返回：一个用户定义的 reader `装饰器 <https://en.wikipedia.org/wiki/Python_syntax_and_semantics#Decorators>`_ 。
 
-返回类型： callable
+返回类型：callable，可调用对象。
\ No newline at end of file
+
+**代码示例**：
+
+.. code-block:: python
+
+    import paddle.reader as reader
+    import time
+
+    def reader_creator_10(dur):
+        def reader():
+            for i in range(10):
+                time.sleep(dur)
+                yield i
+        return reader
+
+    def mapper(x):
+        return (x + 1)
+
+    orders = (True, False)
+    thread_num = (1, 2, 4, 8, 16)
+    buffer_size = (1, 2, 4, 8, 16)
+    for order in orders:
+        for t_num in thread_num:
+            for size in buffer_size:
+                user_reader = reader.xmap_readers(mapper,
+                                                  reader_creator_10(0),
+                                                  t_num, size, order)
+                for n in range(3):
+                    result = list()
+                    for i in user_reader():
+                        result.append(i)
+                    if not order:
+                        result.sort()
+                    for idx, e in enumerate(result):
+                        assert e == mapper(idx)
\ No newline at end of file

doc/fluid/api_cn/layers_cn/isfinite_cn.rst

@@ -5,24 +5,39 @@ isfinite
 
 .. py:function:: paddle.fluid.layers.isfinite(x)
 
-测试x是否包含无穷大/NAN值，如果所有元素都是有穷数，返回Ture,否则返回False
+``注意：此算子的输入 Tensor / LoDTensor 数据类型必须为 int32 / float / double 之一。``
+
+测试 x 是否包含无穷值（即 nan 或 inf）。若元素均为有穷数，返回真；否则返回假。
 
 参数：
-  - **x(variable)** - 用于被检查的Tensor/LoDTensor
+  - **x(variable)** : 变量，包含被测试的 Tensor / LoDTensor。
 
-返回: Variable: tensor变量存储输出值，包含一个bool型数值
+返回: 
+  - Variable (Tensor / LoDTensor)，此 Tensor 变量包含一个 bool 型结果。
 
-返回类型：Variable
+返回类型
+  - Variable (Tensor / LoDTensor)，一个包含 Tensor 的变量。
 
 **代码示例**：
 
 .. code-block:: python
 
     import paddle.fluid as fluid
-    var = fluid.layers.data(name="data",
-                            shape=(4, 6),
-                            dtype="float32")
-    out = fluid.layers.isfinite(var)
+    import numpy
+
+    # Graph Organizing
+    var = fluid.layers.data(name="data", shape=(4, 6), dtype="float32")
+    output = fluid.layers.isfinite(var)
+
+    # Create an executor using CPU as an example
+    exe = fluid.Executor(fluid.CPUPlace())
+    exe.run(fluid.default_startup_program())
+
+    # Execute
+    img = numpy.array((4, 6)).astype(numpy.float32)
+    res, = exe.run(fluid.default_main_program(), feed={'data':img}, fetch_list=[output])
+    print(res)  # Output Value: [ True]
+
 
 
 

doc/fluid/api_cn/layers_cn/lod_reset_cn.rst

@@ -5,84 +5,109 @@ lod_reset
 
 .. py:function:: paddle.fluid.layers.lod_reset(x, y=None, target_lod=None)
 
+根据给定的参数 ``y`` 或 ``target_lod`` ，重设输入 ``x`` (LoDTensor) 的 LoD 信息。
 
-设定 ``x`` 的LoD为 ``y`` 或者 ``target_lod`` 。如果提供 ``y`` ，首先将y.lod指定为目标LoD,否则y.data将指定为目标LoD。如果未提供y，目标LoD则指定为 ``target_lod`` 。如果目标LoD指定为y.data或 ``target_lod`` ，只提供一层LoD。
+参数：
+    - **x** (Variable) : 输入变量，类型为 Tensor 或者 LoDTensor。
+    - **y** (Variable|None) : 当 ``y`` 非空时，输出 LoDTensor 的 LoD 信息将与 ``y`` 的 LoD 一致。
+    - **target_lod** (list|tuple|None) : 一级 LoD，当 ``y`` 为空时，输出 LoDTensor 的 LoD 信息将与 ``target_lod`` 一致。
 
-::
+返回:
+    - Variable (LoDTensor)，重设了 LoD 信息的 LoDTensor。
+
+返回类型：
+    - Variable (LoDTensor)。
 
+抛出异常：
+    - ``TypeError`` : 当 ``y`` 和 ``target_lod`` 二者均为空时抛出此异常。
 
-    * 例1:
+::
+
+    * 例 1:
 
-    给定一级LoDTensor x:
+    x: 包含一级 LoD 信息的 LoDTensor
         x.lod =  [[ 2,           3,                   1 ]]
         x.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]]
         x.dims = [6, 1]
 
+    y: None
+
     target_lod: [4, 2]
 
-    得到一级LoDTensor:
+    Output: 包含一级 LoD 信息的 LoDTensor
         out.lod =  [[4,                          2]]
         out.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]]
         out.dims = [6, 1]
 
-    * 例2:
+    * 例 2:
 
-    给定一级LoDTensor x:
+    x: 包含一级 LoD 信息的 LoDTensor
         x.lod =  [[2,            3,                   1]]
         x.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]]
         x.dims = [6, 1]
 
-    y是张量（Tensor）:
+    y: 普通 Tensor，不含 LoD 信息
         y.data = [[2, 4]]
         y.dims = [1, 3]
 
-    得到一级LoDTensor:
+    target_lod: 当 y 不为空时，此参数不起作用
+
+    Output: 包含一级 LoD 信息的 LoDTensor
         out.lod =  [[2,            4]]
         out.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]]
         out.dims = [6, 1]
 
-    * 例3:
+    * 例 3:
 
-    给定一级LoDTensor x:
+    x: 包含一级 LoD 信息的 LoDTensor
         x.lod =  [[2,            3,                   1]]
         x.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]]
         x.dims = [6, 1]
 
-    y是二级LoDTensor:
+    y: 包含二级 LoD 信息的 LoDTensor
         y.lod =  [[2, 2], [2, 2, 1, 1]]
         y.data = [[1.1], [2.1], [3.1], [4.1], [5.1], [6.1]]
         y.dims = [6, 1]
 
-    得到一个二级LoDTensor:
+    target_lod: 当 y 不为空时，此参数不起作用
+
+    Output: 包含二级 LoD 信息的 LoDTensor
         out.lod =  [[2, 2], [2, 2, 1, 1]]
         out.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]]
         out.dims = [6, 1]
 
-参数：
-    - **x** (Variable)-输入变量，可以为Tensor或者LoDTensor
-    - **y** (Variable|None)-若提供，输出的LoD则衍生自 ``y``
-    - **target_lod** (list|tuple|None)-一层LoD，``y`` 未提供时作为目标LoD
-
-返回：输出变量，该层指定为LoD
-
-返回类型：变量
-
-抛出异常：``TypeError`` - 如果 ``y`` 和 ``target_lod`` 都为空
-
 **代码示例**：
 
 .. code-block:: python
 
     import paddle.fluid as fluid
-    x = fluid.layers.data(name='x', shape=[10])
-    y = fluid.layers.data(name='y', shape=[10, 20], lod_level=2)
-    out = fluid.layers.lod_reset(x=x, y=y)
-
-
-
-
-
-
-
-
-
+    import numpy
+
+    # Graph Organizing
+    x = fluid.layers.data(name='x', shape=[6])
+    y = fluid.layers.data(name='y', shape=[6], lod_level=2)
+    output = fluid.layers.lod_reset(x=x, y=y)
+
+    # Create an executor using CPU as an example
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+
+    # Execute
+    x_tensor = fluid.core.LoDTensor()
+    x_tensor.set(numpy.ones([6]).astype(numpy.float32), place)
+    y_ndarray = numpy.ones([6]).astype(numpy.float32)
+    y_lod = [[2, 2], [2, 2, 1, 1]]
+    y_tensor = fluid.create_lod_tensor(y_ndarray, y_lod, place)
+
+    res, = exe.run(fluid.default_main_program(),
+                   feed={'x':x_tensor, 'y':y_tensor},
+                   fetch_list=[output],
+                   return_numpy=False)
+    print(res)
+    # Output Value:
+    # lod: [[0, 2, 4], [0, 2, 4, 5, 6]]
+    # dim: 6
+    # layout: NCHW
+    # dtype: float
+    # data: [1 1 1 1 1 1]

doc/fluid/api_cn/layers_cn/matmul_cn.rst

 .. _cn_api_fluid_layers_matmul:
 
-
-
 matmul
 -------------------------------
 
 .. py:function:: paddle.fluid.layers.matmul(x, y, transpose_x=False, transpose_y=False, alpha=1.0, name=None)
 
-对两个张量进行矩阵相乘
+输入 ``x`` 和输入 ``y`` 矩阵相乘。
 
-当前输入的张量可以为任意阶，但当任意一个输入的阶数大于3时，两个输入的阶必须相等。
-实际的操作取决于 ``x`` , ``y`` 的维度和 ``transpose_x`` , ``transpose_y`` 的标记值。具体如下：
+两个输入的形状可为任意维度，但当任一输入维度大于3时，两个输入的维度必须相等。
+实际的操作取决于 ``x`` 、 ``y`` 的维度和 ``transpose_x`` 、 ``transpose_y`` 的布尔值。具体如下：
 
-- 如果transpose值为真，则对应 ``tensor`` 的最后两维将被转置。如：``x``是一个shape=[D]的一阶张量，那么 ``x`` 在非转置形式中为[1,D]，在转置形式中为[D,1],而 ``y`` 则相反，在非转置形式中作为[D,1]，在转置形式中作为[1,D]。
+- 如果 ``transpose`` 为真，则对应 Tensor 的后两维会转置。假定 ``x`` 是一个 shape=[D] 的一维 Tensor，则 ``x`` 非转置形状为 [1, D]，转置形状为 [D, 1]。转置之后的输入形状需满足矩阵乘法要求，即 `x_width` 与 `y_height` 相等。
 
-- 转置后，这两个tensors将为 2-D 或 n-D ,并依据下列规则进行矩阵相乘：
-  - 如果两个都是2-D，则同普通矩阵一样进行矩阵相乘
-  - 如果任意一个是n-D，则将其视为驻留在最后两个维度的矩阵堆栈，并在两个张量上应用支持广播的批处理矩阵乘法。
-
-**注意，如果原始张量x或y的秩为1且没有转置，则在矩阵乘法之后，前置或附加维度1将被移除。**
+- 转置后，输入的两个 Tensor 维度将为 2-D 或 n-D，将根据下列规则矩阵相乘：
+    - 如果两个矩阵都是 2-D，则同普通矩阵一样进行矩阵相乘。
+    - 如果任意一个矩阵是 n-D，则将其视为带 batch 的二维矩阵乘法。
 
+- 如果原始 Tensor x 或 y 的秩为 1 且未转置，则矩阵相乘后的前置或附加维度 1 将移除。
 
 参数：
-    - **x** (Variable)-输入变量，类型为Tensor或LoDTensor
-    - **y** (Variable)-输入变量，类型为Tensor或LoDTensor
-    - **transpose_x** (bool)-相乘前是否转置x
-    - **transpose_y** (bool)-相乘前是否转置y
-    - **alpha** (float)-输出比例。默认为1.0
-    - **name** (str|None)-该层名称（可选）。如果设置为空，则自动为该层命名
+    - **x** (Variable) : 输入变量，类型为 Tensor 或 LoDTensor。
+    - **y** (Variable) : 输入变量，类型为 Tensor 或 LoDTensor。
+    - **transpose_x** (bool) : 相乘前是否转置 x。
+    - **transpose_y** (bool) : 相乘前是否转置 y。
+    - **alpha** (float) : 输出比例，默认为 1.0。
+    - **name** (str|None) : 该层名称（可选），如果设置为空，则自动为该层命名。
 
-返回：Tensor或者LoDTensor变量
+返回：
+    - Variable (Tensor / LoDTensor)，矩阵相乘后的结果。
 
-返回类型：变量（Variable）
+返回类型：
+    - Variable（变量）。
 
-**代码示例**：
+::
 
-.. code-block:: python
+    * 例 1:
 
-    # 以下是解释输入和输出维度的示例
-    # x: [B, ..., M, K], y: [B, ..., K, N]
-    # fluid.layers.matmul(x, y)  # out: [B, ..., M, N]
+    x: [B, ..., M, K], y: [B, ..., K, N]
+    out: [B, ..., M, N]
 
-    # x: [B, M, K], y: [B, K, N]
-    # fluid.layers.matmul(x, y)  # out: [B, M, N]
+    * 例 2:
 
-    # x: [B, M, K], y: [K, N]
-    # fluid.layers.matmul(x, y)  # out: [B, M, N]
+    x: [B, M, K], y: [B, K, N]
+    out: [B, M, N]
 
-    # x: [M, K], y: [K, N]
-    # fluid.layers.matmul(x, y)  # out: [M, N]
+    * 例 3:
 
-    # x: [B, M, K], y: [K]
-    # fluid.layers.matmul(x, y)  # out: [B, M]
+    x: [B, M, K], y: [K, N]
+    out: [B, M, N]
 
-    # x: [K], y: [K]
-    # fluid.layers.matmul(x, y)  # out: [1]
+    * 例 4:
 
-    # x: [M], y: [N]
-    # fluid.layers.matmul(x, y, True, True)  # out: [M, N]
+    x: [M, K], y: [K, N]
+    out: [M, N]
 
-    import paddle.fluid as fluid
-    x = fluid.layers.data(name='x', shape=[2, 3], dtype='float32')
-    y = fluid.layers.data(name='y', shape=[3, 2], dtype='float32')
-    out = fluid.layers.matmul(x, y, True, True)
+    * 例 5:
 
+    x: [B, M, K], y: [K]
+    out: [B, M]
 
+    * 例 6:
 
+    x: [K], y: [K]
+    out: [1]
 
+    * 例 7:
 
+    x: [M], y: [N]
+    out: [M, N]
 
 
+**代码示例**：
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    import numpy
+
+    # Graph Organizing
+    x = fluid.layers.data(name='x', shape=[2, 3], dtype='float32')
+    y = fluid.layers.data(name='y', shape=[3, 2], dtype='float32')
+    output = fluid.layers.matmul(x, y, True, True)
+
+    # Create an executor using CPU as an example
+    exe = fluid.Executor(fluid.CPUPlace())
+    exe.run(fluid.default_startup_program())
+
+    # Execute
+    input_x = numpy.ones([2, 3]).astype(numpy.float32)
+    input_y = numpy.ones([3, 2]).astype(numpy.float32)
+    res, = exe.run(fluid.default_main_program(),
+                   feed={'x':input_x, 'y':input_y},
+                   fetch_list=[output])
+    print(res)
+    '''
+    Output Value:
+    [[2. 2. 2.]
+     [2. 2. 2.]
+     [2. 2. 2.]]
+    '''

doc/fluid/api_cn/layers_cn/mean_cn.rst

@@ -5,30 +5,42 @@ mean
 
 .. py:function:: paddle.fluid.layers.mean(x, name=None)
 
-mean算子计算X中所有元素的平均值
+计算 ``x`` 所有元素的平均值。
 
 参数：
-        - **x** (Variable)- (Tensor) 均值运算的输入。
-        - **name** (basestring | None)- 输出的名称。
+        - **x** (Variable) : Tensor 或 LoDTensor。均值运算的输入。
+        - **name** (basestring | None) : 输出变量的名称。
 
-返回：       均值运算输出张量（Tensor）
+返回：
+        - Variable: 包含输出均值的 Tensor / LoDTensor。
 
-返回类型：        Variable
+返回类型：
+        - Variable（变量）。
 
 **代码示例**：
 
 .. code-block:: python
 
     import paddle.fluid as fluid
+    import numpy
+
+    # Graph Organizing
     input = fluid.layers.data(
         name='data', shape=[2, 3], dtype='float32')
-    mean = fluid.layers.mean(input)
-
-
-
-
-
-
-
-
-
+    output = fluid.layers.mean(input)
+
+    # Create an executor using CPU as an example
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+
+    # Execute
+    x_ndarray = numpy.ones([2, 3]).astype(numpy.float32)
+    res, = exe.run(fluid.default_main_program(),
+                   feed={'data':x_ndarray},
+                   fetch_list=[output])
+    print(res)
+    '''
+    Output Value:
+    [1.]
+    '''

doc/fluid/api_cn/layers_cn/merge_selected_rows_cn.rst

@@ -5,51 +5,61 @@ merge_selected_rows
 
 .. py:function:: paddle.fluid.layers.merge_selected_rows(x, name=None)
 
-**实现合并选中行（row）操作**
-
-该运算用于合并（值相加）输入张量中重复的行。输出行没有重复的行，并且按值从小到大顺序重新对行排序。
-
-::
-
-    例如：
-
-          输入:
-               X.rows = [0, 5, 5, 4, 19]
-               X.height = 20
-               X.value = [[1, 1] [2, 2] [3, 3] [4, 4] [6, 6]]
-
-
-          输出：
-               Out.row is [0, 4, 5, 19]
-               Out.height is 20
-               Out.value is: [[1, 1] [4, 4] [5, 5] [6, 6]]
-
-
+累加合并 `SelectedRows <https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/framework/selected_rows.h>`_ ( ``x`` ) 中的重复行，并对行值由小到大重新排序。
 
 参数:
-  - x (Variable) – 输入类型为SelectedRows, 选中行有可能重复
-  - name (basestring|None) – 输出变量的命名
+  - x (Variable) : 类型为 SelectedRows，选中行允许重复。
+  - name (basestring|None) : 输出变量名称。
 
-返回: 输出类型为SelectedRows，并且选中行不会重复
+返回:
+  - 含有 SelectedRows 的 Variable，选中行不重复。
 
-返回类型: 变量（Variable）
+返回类型:
+  - Variable（变量）。
 
 **代码示例**
 
 ..  code-block:: python
 
   import paddle.fluid as fluid
-  b = fluid.default_main_program().global_block()
-  var = b.create_var(
-        name="X", dtype="float32", persistable=True,
-        type=fluid.core.VarDesc.VarType.SELECTED_ROWS)
-  y = fluid.layers.merge_selected_rows(var)
-
-
-
-
-
-
-
+  import numpy
 
+  place = fluid.CPUPlace()
+  block = fluid.default_main_program().global_block()
 
+  var = block.create_var(name="X2",
+                         dtype="float32",
+                         persistable=True,
+                         type=fluid.core.VarDesc.VarType.SELECTED_ROWS)
+  y = fluid.layers.merge_selected_rows(var)
+  z = fluid.layers.get_tensor_from_selected_rows(y)
+
+  x_rows = [0, 2, 2, 4, 19]
+  row_numel = 2
+  np_array = numpy.ones((len(x_rows), row_numel)).astype("float32")
+
+  x = fluid.global_scope().var("X2").get_selected_rows()
+  x.set_rows(x_rows)
+  x.set_height(20)
+  x_tensor = x.get_tensor()
+  x_tensor.set(np_array, place)
+
+  exe = fluid.Executor(place=place)
+  result = exe.run(fluid.default_main_program(), fetch_list=[z])
+
+  print("x_rows: ", x_rows)
+  print("np_array: ", np_array)
+  print("result: ", result)
+  '''
+  Output Values:
+  ('x_rows: ', [0, 2, 2, 4, 19])
+  ('np_array: ', array([[1., 1.],
+         [1., 1.],
+         [1., 1.],
+         [1., 1.],
+         [1., 1.]], dtype=float32))
+  ('result: ', [array([[1., 1.],
+         [2., 2.],
+         [1., 1.],
+         [1., 1.]], dtype=float32)])
+  '''