[docs_epoch1]update 50+ paddle.* API docs (PaddlePaddle#4801)

* docs_epoch1

* updata to_tensor

* Update clip_cn.rst

* Update median_cn.rst

* Update prod_cn.rst

* Update var_cn.rst

* Update randperm_cn.rst

* Update randperm_cn.rst

* Update diag_cn.rst

* Update roll_cn.rst

* Update bmm_cn.rst

* Update histogram_cn.rst

* Update flip_cn.rst

* Update roll_cn.rst

* Update load_cn.rst

* Update histogram_cn.rst

* Update load_cn.rst

docs/api/paddle/addmm_cn.rst

@@ -9,7 +9,7 @@ addmm
 
 
 
-计算x和y的乘积，将结果乘以标量alpha，再加上input与beta的乘积，得到输出。其中input与x、y乘积的维度必须是可广播的。
+计算 x 和 y 的乘积，将结果乘以标量 alpha，再加上 input 与 beta 的乘积，得到输出。其中 input 与 x、y 乘积的维度必须是可广播的。
 
 计算过程的公式为：
 
@@ -19,16 +19,16 @@ addmm
 参数
 ::::::::::::
 
-    - **input** （Tensor）：输入Tensor input，数据类型支持float32，float64。
-    - **x** （Tensor）：输入Tensor x，数据类型支持float32，float64。
-    - **y** （Tensor）：输入Tensor y，数据类型支持float32，float64。
-    - **alpha** （float，可选）：乘以x*y的标量，数据类型支持float32，float64，默认值为1.0。
-    - **beta** （float，可选）：乘以input的标量，数据类型支持float32，float64，默认值为1.0。
-    - **name** （str，可选）：具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
+    - **input** (Tensor) - 输入 Tensor input，数据类型支持 float32、float64。
+    - **x** (Tensor) - 输入 Tensor x，数据类型支持 float32、float64。
+    - **y** (Tensor) - 输入 Tensor y，数据类型支持 float32、float64。
+    - **alpha** (float，可选) - 乘以x*y的标量，数据类型支持float32、float64，默认值为1.0。
+    - **beta** (float，可选) - 乘以input的标量，数据类型支持float32、float64，默认值为1.0。
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None。
 
 返回
 ::::::::::::
-计算得到的Tensor。Tensor数据类型与输入input数据类型一致。
+计算得到的 Tensor。Tensor 数据类型与输入 input 数据类型一致。
 
 代码示例
 ::::::::::::

docs/api/paddle/arange_cn.rst

@@ -5,21 +5,21 @@ arange
 
 .. py:function:: paddle.arange(start=0, end=None, step=1, dtype=None, name=None)
 
-该OP返回以步长 ``step`` 均匀分隔给定数值区间[``start``, ``end``)的1-D Tensor，数据类型为 ``dtype``。
+返回以步长 ``step`` 均匀分隔给定数值区间[ ``start`` , ``end`` )的1-D Tensor，数据类型为 ``dtype`` 。
 
-当 ``dtype`` 表示浮点类型时，为了避免浮点计算误差，建议给 ``end`` 加上一个极小值epsilon，使边界可以更加明确。
+当 ``dtype`` 表示浮点类型时，为了避免浮点计算误差，建议给 ``end`` 加上一个极小值 epsilon，使边界可以更加明确。
 
 参数
 ::::::::::
-        - **start** (float|int|Tensor) - 区间起点（且区间包括此值）。当 ``start`` 类型是Tensor时，是形状为[1]且数据类型为int32、int64、float32、float64的Tensor。如果仅指定 ``start`` ，而 ``end`` 为None，则区间为[0, ``start``)。默认值为0。
-        - **end** (float|int|Tensor, 可选) - 区间终点（且通常区间不包括此值）。当 ``end`` 类型是Tensor时，是形状为[1]且数据类型为int32、int64、float32、float64的Tensor。默认值为None。
-        - **step** (float|int|Tensor, 可选) - 均匀分割的步长。当 ``step`` 类型是Tensor时，是形状为[1]且数据类型为int32、int64、float32、float64的Tensor。默认值为1。
-        - **dtype** (str|np.dtype, 可选) - 输出Tensor的数据类型，支持int32、int64、float32、float64。当该参数值为None时， 输出Tensor的数据类型为int64。默认值为None.
-        - **name** (str, 可选) - 输出的名字。一般无需设置，默认值为None。该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。
+        - **start** (float|int|Tensor) - 区间起点（且区间包括此值）。当 ``start`` 类型是 Tensor 时，是形状为[1]且数据类型为 int32、int64、float32、float64 的 Tensor。如果仅指定 ``start`` ，而 ``end`` 为 None，则区间为[0, ``start``)。默认值为0。
+        - **end** (float|int|Tensor，可选) - 区间终点（且通常区间不包括此值）。当 ``end`` 类型是 Tensor 时，是形状为[1]且数据类型为 int32、int64、float32、float64 的 Tensor。默认值为 None。
+        - **step** (float|int|Tensor，可选) - 均匀分割的步长。当 ``step`` 类型是 Tensor 时，是形状为[1]且数据类型为 int32、int64、float32、float64的Tensor。默认值为1。
+        - **dtype** (str|np.dtype，可选) - 输出 Tensor 的数据类型，支持 int32、int64、float32、float64。当该参数值为 None 时， 输出Tensor的数据类型为int64。默认值为None.
+        - **name** (str，可选) - 操作的名称(可选，默认值为None)。更多信息请参见 :ref:`api_guide_Name`。
 
 返回
 ::::::::::
-        Tensor: 以步长 ``step`` 均匀分割给定数值区间[``start``, ``end``)后得到的1-D Tensor, 数据类型为 ``dtype`` 。
+        Tensor，以步长 ``step`` 均匀分割给定数值区间[start, end)后得到的1-D Tensor，数据类型为 ``dtype`` 。
 
 
 代码示例

docs/api/paddle/argmax_cn.rst

@@ -10,37 +10,18 @@ argmax
 
 参数
 ::::::::
-    - **x** （Tensor） - 输入的多维 ``Tensor`` ，支持的数据类型：float32、float64、int16、int32、int64、uint8。
-    - **axis** （int，可选） - 指定对输入Tensor进行运算的轴， ``axis`` 的有效范围是[-R, R），R是输入 ``x`` 的维度个数， ``axis`` 为负数时，进行计算的 ``axis`` 与 ``axis`` + R 一致。默认值为None, 将会对输入的 `x` 进行平铺展开，返回最大值的索引。
-    - **keepdim** （bool，可选）- 是否在输出Tensor中保留减小的维度。如果 keepdim 为True，则输出Tensor和 x 具有相同的维度(减少的维度除外，减少的维度的大小为1)，默认值为False。
-    - **dtype** （np.dtype|str，可选）- 输出Tensor的数据类型，可选值为int32，int64，默认值为int64，将返回int64类型的结果。
-    - **name** （str，可选） – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
+    - **x** (Tensor) - 输入的多维 ``Tensor`` ，支持的数据类型：float32、float64、int16、int32、int64、uint8。
+    - **axis** (int，可选) - 指定对输入Tensor进行运算的轴， ``axis`` 的有效范围是[-R, R），R是输入 ``x`` 的维度个数， ``axis`` 为负数时，进行计算的 ``axis`` 与 ``axis`` + R 一致。默认值为None, 将会对输入的 `x` 进行平铺展开，返回最大值的索引。
+    - **keepdim** (bool，可选) - 是否在输出Tensor中保留减小的维度。如果 keepdim 为True，则输出Tensor和 x 具有相同的维度(减少的维度除外，减少的维度的大小为1)，默认值为False。
+    - **dtype** (np.dtype|str，可选) - 输出Tensor的数据类型，可选值为int32，int64，默认值为int64，将返回int64类型的结果。
+    - **name** (str，可选) - 操作的名称(可选，默认值为None)。更多信息请参见 :ref:`api_guide_Name`。
 
 返回
 ::::::::
-``Tensor``, 如果设置 :attr:`dtype` 为 `int32` 时，返回的tensor的数据类型为 `int32` ，其它情况将返回的tensor的数据类型为 `int64` 。
+``Tensor`` ，如果设置 :attr:`dtype` 为 int32 时，返回的 Tensor 的数据类型为 int32，其它情况将返回的 Tensor 的数据类型为 int64。
 
 
 示例代码
 ::::::::
 
-.. code-block:: python
-
-     import numpy as np
-     import paddle
-
-     data = [[5,8,9,5],
-             [0,0,1,7],
-             [6,9,2,4]]
-     x =  paddle.to_tensor(data)
-     out1 = paddle.argmax(x)
-     print(out1) # 2
-     out2 = paddle.argmax(x, axis=0)
-     print(out2) 
-     # [2, 2, 0, 1]
-     out3 = paddle.argmax(x, axis=-1)
-     print(out3) 
-     # [2 3 1]
-     out4 = paddle.argmax(x, axis=0, keepdim=True)
-     print(out4)
-     # [[2, 2, 0, 1]]
+COPY-FROM: paddle.argmax

docs/api/paddle/bmm_cn.rst

@@ -3,25 +3,23 @@
 bmm
 -------------------------------
 
-.. py:function:: paddle.bmm(x, y, name=None):
+.. py:function:: paddle.bmm(x, y, name=None)
 
 
 
 
 对输入x及输入y进行矩阵相乘。
 
-两个输入的维度必须等于3，并且矩阵x和矩阵y的第一维必须相等
+两个输入的维度必须等于3，并且矩阵x和矩阵y的第一维必须相等。同时矩阵x的第二维必须等于矩阵y的第三维。
 
-同时矩阵x的第二维必须等于矩阵y的第三维
-
-例如：若x和y分别为（b, m, k）和 （b, k, n)的矩阵，则函数的输出为一个（b, m, n）的矩阵
+例如：若 x 和 y 分别为 (b, m, k) 和 (b, k, n) 的矩阵，则函数的输出为一个 (b, m, n) 的矩阵。
 
 参数
 :::::::::
 
-    - **x** (Tensor) : 输入变量，类型为 Tensor。
-    - **y** (Tensor) : 输入变量，类型为 Tensor。
-    - **name** (str|None) : 该层名称（可选），如果设置为空，则自动为该层命名。
+    - **x** (Tensor) - 输入变量，类型为 Tensor。
+    - **y** (Tensor) - 输入变量，类型为 Tensor。
+    - **name** (str，可选) - 操作的名称(可选，默认值为None)。更多信息请参见 :ref:`api_guide_Name`。
 
 返回
 :::::::::
@@ -30,21 +28,5 @@ Tensor，矩阵相乘后的结果。
 代码示例
 :::::::::
 
-.. code-block:: python
-    
-    import paddle
-
-    # In imperative mode:
-    # size x: (2, 2, 3) and y: (2, 3, 2)
-    x = paddle.to_tensor([[[1.0, 1.0, 1.0],
-                            [2.0, 2.0, 2.0]],
-                            [[3.0, 3.0, 3.0],
-                            [4.0, 4.0, 4.0]]])
-    y = paddle.to_tensor([[[1.0, 1.0],[2.0, 2.0],[3.0, 3.0]],
-                            [[4.0, 4.0],[5.0, 5.0],[6.0, 6.0]]])
-    out = paddle.bmm(x, y)
-    #output size: (2, 2, 2)
-    #output value:
-    #[[[6.0, 6.0],[12.0, 12.0]],[[45.0, 45.0],[60.0, 60.0]]]
-    out_np = out.numpy()
+COPY-FROM: paddle.bmm
 

docs/api/paddle/broadcast_to_cn.rst

@@ -11,8 +11,8 @@ broadcast_to
 
 参数
 :::::::::
-    - x (Tensor) - 输入的Tensor，数据类型为：bool、float32、float64、int32或int64。
-    - shape (tuple|list|Tensor) - 给定输入 ``x`` 扩展后的形状,若 ``shape`` 为list或者tuple，则其中的元素值应该为整数或者1-D Tensor，若 ``shape`` 类型为Tensor，则其应该为1-D Tensor。
+    - x (Tensor) - 输入的 Tensor，数据类型为：bool、float32、float64、int32或int64。
+    - shape (tuple|list|Tensor) - 给定输入 ``x`` 扩展后的形状，若 ``shape`` 为 list 或者 tuple，则其中的元素值应该为整数或者1-D Tensor，若 ``shape`` 类型为 Tensor，则其应该为1-D Tensor。
     - name (str，可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。
 
 返回

docs/api/paddle/clip_cn.rst

@@ -17,10 +17,10 @@ clip
 参数
 ::::::::::::
 
-    - x (Tensor) - 输入的Tensor，数据类型为：float32、float64。
-    - min (float32|Tensor, 可选) - 裁剪的最小值，输入中小于该值的元素将由该元素代替，若参数为空，则不对输入的最小值做限制。数据类型可以是float32或形状为[1]的Tensor，类型可以为int32，float32，float64，默认值为None。
-    - max (float32|Tensor, 可选) - 裁剪的最大值，输入中大于该值的元素将由该元素代替，若参数为空，则不对输入的最大值做限制。数据类型可以是float32或形状为[1]的Tensor，类型可以为int32，float32，float64，默认值为None。
-    - name (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
+    - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64、int32、int64。
+    - **min** (float32|Tensor，可选) - 裁剪的最小值，输入中小于该值的元素将由该元素代替，若参数为空，则不对输入的最小值做限制。数据类型可以是 float32 或形状为[1]的 Tensor，类型可以为int32、float32、float64，默认值为 None。
+    - **max** (float32|Tensor，可选) - 裁剪的最大值，输入中大于该值的元素将由该元素代替，若参数为空，则不对输入的最大值做限制。数据类型可以是 float32 或形状为[1]的 Tensor，类型可以为int32、float32、float64，默认值为 None。
+    - **name** (str，可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
 
 返回
 ::::::::::::

docs/api/paddle/concat_cn.rst

@@ -6,18 +6,18 @@ concat
 .. py:function:: paddle.concat(x, axis=0, name=None)
 
 
-对输入沿参数 ``axis`` 轴进行联结，返回一个新的Tensor。
+对输入沿参数 ``axis`` 轴进行联结，返回一个新的 Tensor。
 
 参数
 ::::::::::::
 
-    - **x** (list|tuple) - 待联结的Tensor list或者Tensor tuple ，支持的数据类型为：bool、float16、float32、float64、int32、int64、uint8， ``x`` 中所有Tensor的数据类型应该一致。
-    - **axis** (int|Tensor，可选) - 指定对输入 ``x`` 进行运算的轴，可以是整数或者形状为[1]的Tensor，数据类型为int32或者int64。 ``axis`` 的有效范围是[-R, R)，R是输入 ``x`` 中Tensor的维度， ``axis`` 为负值时与 :math:`axis + R` 等价。默认值为0。
+    - **x** (list|tuple) - 待联结的 Tensor list 或者 Tensor tuple ，支持的数据类型为：bool、float16、float32、float64、int32、int64、uint8， ``x`` 中所有 Tensor 的数据类型应该一致。
+    - **axis** (int|Tensor，可选) - 指定对输入 ``x`` 进行运算的轴，可以是整数或者形状为[1]的Tensor，数据类型为 int32 或者 int64。 ``axis`` 的有效范围是 [-R, R)，R是输入 ``x`` 中 Tensor 的维度， ``axis`` 为负值时与 :math:`axis + R` 等价。默认值为0。
     - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
 
 返回
 ::::::::::::
-联结后的Tensor ，数据类型和 ``x`` 中的Tensor相同。
+联结后的 Tensor，数据类型和 ``x`` 中的 Tensor 相同。
 
 
 代码示例

docs/api/paddle/diag_cn.rst

@@ -18,10 +18,10 @@ diag
 
 参数
 :::::::::
-    - x（Tensor）：输入的 `Tensor`。它的形状可以是一维或二维。其数据类型应为float32，float64，int32，int64。
-    - offset（int，可选）：对角线偏移量。正值表示上对角线，0表示主对角线，负值表示下对角线。
-    - padding_value（int|float，可选）：使用此值来填充指定对角线以外的区域。仅在输入为一维张量时生效。默认值为0。
-    - name (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
+    - **x** (Tensor) - 输入的 `Tensor`。它的形状可以是一维或二维。其数据类型应为float32、float64、int32、int64。
+    - **offset** (int，可选) - 对角线偏移量。正值表示上对角线，0表示主对角线，负值表示下对角线。
+    - **padding_value** (int|float，可选) -使用此值来填充指定对角线以外的区域。仅在输入为一维张量时生效。默认值为0。
+    - **name** (str，可选）- 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
 
 返回
 :::::::::

docs/api/paddle/empty_cn.rst

@@ -7,44 +7,20 @@ empty
 
 
 
-创建形状大小为shape并且数据类型为dtype的Tensor，其中元素值是未初始化的。
+创建形状大小为 shape 并且数据类型为 dtype 的 Tensor，其中元素值是未初始化的。
 
 参数
 ::::::::::::
 
-    - **shape** (list|tuple|Tensor) – 指定创建Tensor的形状(shape)，数据类型为int32 或者int64。
-    - **dtype** （np.dtype|str， 可选）- 输出变量的数据类型，可以是bool、float16、float32、float64、int32、int64。若为None，则输出变量的数据类型为系统全局默认类型，默认值为None。
-    - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为None。
+    - **shape** (list|tuple|Tensor) – 指定创建 Tensor 的形状(shape)，数据类型为 int32 或者 int64。
+    - **dtype** （np.dtype|str，可选）- 输出变量的数据类型，可以是 bool、float16、float32、float64、int32、int64。若为 None，则输出变量的数据类型为系统全局默认类型，默认值为 None。
+    - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
 
 返回
 ::::::::::::
-返回一个根据 ``shape`` 和 ``dtype`` 创建并且尚未初始化的Tensor。
+返回一个根据 ``shape`` 和 ``dtype`` 创建并且尚未初始化的 Tensor。
 
 代码示例
 ::::::::::::
 
-.. code-block:: python
-
-    import paddle
-    import numpy as np
-
-    paddle.set_device("cpu")  # and use cpu device
-
-    # example 1: argument ``shape`` is a list which doesn't contain Tensor.
-    data1 = paddle.empty(shape=[2,3], dtype='float32')
-    #[[4.3612203e+27 1.8176809e+31 1.3555911e-19]     # uninitialized
-    # [1.1699684e-19 1.3563156e-19 3.6408321e-11]]    # uninitialized
-
-    # example 2: argument ``shape`` is a Tensor, the data type must be int64 or int32.
-    shape_data = np.array([2, 3]).astype('int32')
-    shape = paddle.to_tensor(shape_data)
-    data2 = paddle.empty(shape=shape, dtype='float32')
-    #[[1.7192326e-37 4.8125365e-38 1.9866003e-36]     # uninitialized
-    # [1.3284029e-40 7.1117408e-37 2.5353012e+30]]    # uninitialized
-
-    # example 3: argument ``shape`` is a list which contains Tensor.
-    dim2_data = np.array([3]).astype('int32')
-    dim2 = paddle.to_tensor(dim2_data)
-    data3 = paddle.empty(shape=[2, dim2], dtype='float32')
-    #[[1.1024214e+24 7.0379409e+22 6.5737699e-34]     # uninitialized
-    # [7.5563101e+31 7.7130405e+31 2.8020654e+20]]    # uninitialized
+COPY-FROM: paddle.empty

docs/api/paddle/equal_cn.rst

@@ -5,21 +5,22 @@ equal
 .. py:function:: paddle.equal(x, y, name=None)
 
 
-返回 :math:`x==y` 逐元素比较x和y是否相等，相同位置的元素相同则返回True，否则返回False。使用重载算子 `==` 可以有相同的计算函数效果
+返回 :math:`x==y` 逐元素比较 x 和 y 是否相等，相同位置的元素相同则返回 True，否则返回 False。使用重载算子 `==` 可以有相同的计算函数效果。
 
-**注：输出的结果不返回梯度。**
+.. note::
+    输出的结果不返回梯度。
 
 参数
 ::::::::::::
 
     - **x** (Tensor) - 输入Tensor，支持的数据类型包括 bool、float32、float64、int32、int64。
     - **y** (Tensor) - 输入Tensor，支持的数据类型包括 bool、float32、float64、int32、int64。
-    - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
 
 
 返回
 ::::::::::::
-输出结果的Tensor，输出Tensor的shape和输入一致，Tensor数据类型为bool。
+输出结果的 Tensor，输出 Tensor 的 shape 和输入一致，Tensor 数据类型为 bool。
 
 代码示例
 ::::::::::::

docs/api/paddle/erf_cn.rst

@@ -3,7 +3,7 @@
 erf
 -------------------------------
 
-.. py:function:: paddle.erf(x,name = None)
+.. py:function:: paddle.erf(x, name = None)
 
 
 
@@ -17,8 +17,8 @@ erf
 参数
 ::::::::::::
 
-  - **x** (Tensor) - Erf Op 的输入，多维 Tensor，数据类型为 float16、float32 或 float64。
-  - **name** (str，可选) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为 None。
+  - **x** (Tensor) - 输入的多维 Tensor，数据类型为 float16、float32 或 float64。
+  - **name** (str，可选) - 操作的名称(可选，默认值为None)。更多信息请参见 :ref:`api_guide_Name`。
 
 返回
 ::::::::::::