Fix some docs for create_lod_tensor, create_random_int_lodtensor, ParamAttr (#1203)

* fix docs, test=develop

* fix LoDTensor ref bug, test=develop

* follow lanxianghit's comments, test=develop

* add range of output random int tensor, test=develop

doc/fluid/api_cn/fluid_cn/ParamAttr_cn.rst

@@ -7,16 +7,20 @@ ParamAttr
 
 .. py:class:: paddle.fluid.ParamAttr(name=None, initializer=None, learning_rate=1.0, regularizer=None, trainable=True, gradient_clip=None, do_model_average=False)
 
-该类代表了参数的各种属性。 为了使神经网络训练过程更加流畅，用户可以根据需要调整参数属性。比如learning rate（学习率）, regularization（正则化）, trainable（可训练性）, do_model_average(平均化模型)和参数初始化方法.
+创建一个参数属性对象，用户可设置参数的名称、初始化方式、学习率、正则化规则、是否需要训练、梯度裁剪方式、是否做模型平均等属性。
 
 参数:
-    - **name** (str) – 参数名。默认为None。
-    - **initializer** (Initializer) – 初始化该参数的方法。 默认为None
-    - **learning_rate** (float) – 参数的学习率。计算方法为 :math:`global\_lr*parameter\_lr∗scheduler\_factor` 。 默认为1.0
-    - **regularizer** (WeightDecayRegularizer) – 正则因子. 默认为None
-    - **trainable** (bool) – 该参数是否可训练。默认为True
-    - **gradient_clip** (BaseGradientClipAttr) – 减少参数梯度的方法。默认为None
-    - **do_model_average** (bool) – 该参数是否服从模型平均值。默认为False
+    - **name** (str，可选) - 参数的名称。默认值为None，表示框架自动创建参数的名称。
+    - **initializer** (Initializer，可选) - 参数的初始化方式。默认值为None，表示权重参数采用Xavier初始化方式，偏置参数采用全0初始化方式。
+    - **learning_rate** (float) - 参数的学习率。实际参数的学习率等于全局学习率乘以参数的学习率，再乘以learning rate schedule的系数。
+    - **regularizer** (WeightDecayRegularizer，可选) - 正则化因子。默认值为None，表示没有正则化因子。
+    - **trainable** (bool) - 参数是否需要训练。默认值为True，表示需要训练。
+    - **gradient_clip** (BaseGradientClipAttr，可选) - 梯度裁剪方式。默认值为None，表示不需要梯度裁剪。
+    - **do_model_average** (bool) - 是否做模型平均。默认值为False，表示不做模型平均。
+
+返回: 表示参数属性的对象。
+
+返回类型: ParamAttr
 
 **代码示例**
 
@@ -28,18 +32,8 @@ ParamAttr
                                    learning_rate=0.5,
                                    regularizer=fluid.regularizer.L2Decay(1.0),
                                    trainable=True)
+   print(w_param_attrs.name) # "fc_weight"
    x = fluid.layers.data(name='X', shape=[1], dtype='float32')
    y_predict = fluid.layers.fc(input=x, size=10, param_attr=w_param_attrs)
 
 
-
-
-
-
-
-
-
-
-
-
-

doc/fluid/api_cn/fluid_cn/create_lod_tensor_cn.rst

@@ -6,45 +6,41 @@ create_lod_tensor
 
 .. py:function:: paddle.fluid.create_lod_tensor(data, recursive_seq_lens, place)
 
+从一个numpy数组、list或LoDTensor创建一个新的LoDTensor。
 
-该函数从一个numpy数组，列表或者已经存在的lod tensor中创建一个lod tensor。
+具体实现方法如下:
 
-通过一下几步实现:
+1. 检查基于序列长度的LoD（length-based LoD），即参数中的 :code:`recursive_seq_lens` 是否正确。
 
-1. 检查length-based level of detail (LoD,长度为基准的细节层次)，或称recursive_sequence_lengths(递归序列长度)的正确性
+2. 将 :code:`recursive_seq_lens` 转换为基于偏移量的LoD（offset-based LoD）。
 
-2. 将recursive_sequence_lengths转化为offset-based LoD(偏移量为基准的LoD)
+3. 根据place参数，把所提供的 :code:`data` （numpy数组、list或LoDTensor）的数据复制到CPU或GPU上。
 
-3. 把提供的numpy数组，列表或者已经存在的lod tensor复制到CPU或GPU中(依据执行场所确定)
+4. 将基于偏移量的LoD设置到输出的LoDTensor中。
 
-4. 利用offset-based LoD来设置LoD
+假设我们想创建一个LoDTensor表示词的序列，其中每个词用一个整数id表示。若待创建的LoDTensor表示2个句子，其中一个句子包含2个单词，另一个句子包含3个单词。
 
-例如：
-假如我们想用LoD Tensor来承载一词序列的数据，其中每个词由一个整数来表示。现在，我们意图创建一个LoD Tensor来代表两个句子，其中一个句子有两个词，另外一个句子有三个。那么数 ``data`` 可以是一个numpy数组，形状为（5,1）。同时， ``recursive_seq_lens`` 为 [[2, 3]]，表明各个句子的长度。这个长度为基准的 ``recursive_seq_lens`` 将在函数中会被转化为以偏移量为基准的 LoD [[0, 2, 5]]。
+那么， :code:`data` 为一个维度为(5, 1)的numpy整数数组； :code:`recursive_seq_lens` 为[[2, 3]]，表示每个句子含的单词个数。在该接口内部，基于序列长度的
+:code:`recursive_seq_lens` [[2, 3]]会转换为为基于偏移量的LoD [[0, 2, 5]]。
 
-.. code-block:: python
-
-        import paddle.fluid as fluid
-        import numpy as np
-     
-        t = fluid.create_lod_tensor(np.ndarray([5, 30]), [[2, 3]], fluid.CPUPlace())
-
-参考 :ref:`api_guide_tensor` 以获取更多关于LoD的信息。
+请查阅 :ref:`cn_user_guide_lod_tensor` 了解更多关于LoD的介绍。
 
 参数:
-  - **data** (numpy.ndarray|list|LoDTensor) – 容纳着待复制数据的一个numpy数组、列表或LoD Tensor
-  - **recursive_seq_lens** (list) – 一组列表的列表， 表明了由用户指明的length-based level of detail信息
-  - **place** (Place) – CPU或GPU。 指明返回的新LoD Tensor存储地点
-
-返回: 一个fluid LoDTensor对象，包含数据和 ``recursive_seq_lens`` 信息
-
-
-
-
+    - **data** (numpy.ndarray|list|LoDTensor) - 表示LoDTensor数据的numpy数组、list或LoDTensor。
+    - **recursive_seq_lens** (list[list[int]]) - 基于序列长度的LoD信息。
+    - **place** (CPUPlace|CUDAPlace) - 表示返回的LoDTensor存储在CPU或GPU place中。
 
+返回: 包含数据信息和序列长度信息的LoDTensor。
 
+返回类型: LoDTensor
 
+**代码示例**
 
+.. code-block:: python
 
+        import paddle.fluid as fluid
+        import numpy as np
+     
+        t = fluid.create_lod_tensor(np.ndarray([5, 30]), [[2, 3]], fluid.CPUPlace())
 
 

doc/fluid/api_cn/fluid_cn/create_random_int_lodtensor_cn.rst

@@ -6,29 +6,27 @@ create_random_int_lodtensor
 
 .. py:function:: paddle.fluid.create_random_int_lodtensor(recursive_seq_lens, base_shape, place, low, high)
 
+创建一个包含随机整数的LoDTensor。
 
+具体实现方法如下：
 
-该函数创建一个存储多个随机整数的LoD Tensor。
+1. 基于序列长度 :code:`recursive_seq_lens` 和 :code:`base_shape` 产生返回值的维度。返回值的第一维等于序列总长度，其余维度为 :code:`base_shape` 。
 
-该函数是经常在书中出现的案例，所以我们根据新的API： ``create_lod_tensor`` 更改它然后放在LoD Tensor板块里来简化代码。
+2. 创建一个包含随机整数的numpy数组，并作为 :code:`data` 参数传入 :ref:`cn_api_fluid_create_lod_tensor` 接口中创建LoDTensor返回。
 
-该函数实现以下功能：
-
-1. 根据用户输入的length-based ``recursive_seq_lens`` （基于长度的递归序列长）和在 ``basic_shape`` 中的基本元素形状计算LoDTensor的整体形状
-2. 由此形状，建立numpy数组
-3. 使用API： ``create_lod_tensor`` 建立LoDTensor
-
-
-假如我们想用LoD Tensor来承载一词序列，其中每个词由一个整数来表示。现在，我们意图创建一个LoD Tensor来代表两个句子，其中一个句子有两个词，另外一个句子有三个。那么 ``base_shape`` 为[1], 输入的length-based ``recursive_seq_lens`` 是 [[2, 3]]。那么LoDTensor的整体形状应为[5, 1]，并且为两个句子存储5个词。
+假设我们想创建一个LoDTensor表示序列信息，共包含2个序列，维度分别为[2, 30]和[3, 30]，那么序列长度 :code:`recursive_seq_lens` 传入[[2, 3]]，:code:`base_shape` 传入[30]（即除了序列长度以外的维度）。
+最后返回的LoDTensor的维度为[5, 30]，其中第一维5为序列总长度，其余维度为 :code:`base_shape` 。
 
 参数:
-    - **recursive_seq_lens** (list) – 一组列表的列表， 表明了由用户指明的length-based level of detail信息
-    - **base_shape** (list) – LoDTensor所容纳的基本元素的形状
-    - **place** (Place) –  CPU或GPU。 指明返回的新LoD Tensor存储地点
-    - **low** (int) – 随机数下限
-    - **high** (int) – 随机数上限
+    - **recursive_seq_lens** (list[list[int]]) - 基于序列长度的LoD信息。
+    - **base_shape** (list) - 除第一维以外输出结果的维度信息。
+    - **place** (CPUPlace|CUDAPlace) - 表示返回的LoDTensor存储在CPU或GPU place中。
+    - **low** (int) - 随机整数的下限值。
+    - **high** (int) - 随机整数的上限值，必须大于或等于low。
+
+返回: 包含随机整数数据信息和序列长度信息的LoDTensor，数值范围在[low, high]之间。
 
-返回: 一个fluid LoDTensor对象，包含张量数据和 ``recursive_seq_lens`` 信息
+返回类型: LoDTensor
 
 **代码示例**
 
@@ -37,4 +35,5 @@ create_random_int_lodtensor
         import paddle.fluid as fluid
      
         t = fluid.create_random_int_lodtensor(recursive_seq_lens=[[2, 3]],base_shape=[30], place=fluid.CPUPlace(), low=0, high=10)
+        print(t.shape()) # [5, 30]