[API compatibility] add docs for requires_grad, var, mean, multinomial, rand_like (PaddlePaddle#7422)

* add apis

* fix alias, kwargs

* Update docs/api/paddle/mean_cn.rst

* Update docs/api/paddle/multinomial_cn.rst

---------

Co-authored-by: zachary sun <[email protected]>

Author: LLSGYN

docs/api/paddle/Overview_cn.rst

@@ -426,6 +426,7 @@ tensor random 相关
     " :ref:`paddle.randint_like <cn_api_paddle_randint_like>` ", "返回一个和 x 具有相同形状的服从均匀分布的、范围在[low, high)的随机 Tensor，数据类型为 dtype 或者和 x 相同。"
     " :ref:`paddle.randn <cn_api_paddle_randn>` ", "返回符合标准正态分布（均值为 0，标准差为 1 的正态随机分布）的随机 Tensor"
     " :ref:`paddle.randn_like <cn_api_paddle_randn_like>` ", "返回一个和 x 具有相同形状的服从标准正态分布（均值为 0，标准差为 1 的正态随机分布）的随机 Tensor，数据类型为 dtype 或者和 x 相同。"
+    " :ref:`paddle.rand_like <cn_api_paddle_rand_like>` ", "返回一个和 x 具有相同形状的服从均匀分布的、范围在[0, 1)的随机 Tensor，数据类型为 dtype 或者和 x 相同。"
     " :ref:`paddle.randperm <cn_api_paddle_randperm>` ", "返回一个数值在 0 到 n-1、随机排列的 1-D Tensor"
     " :ref:`paddle.seed <cn_api_paddle_seed>` ", "设置全局默认 generator 的随机种子"
     " :ref:`paddle.uniform <cn_api_paddle_uniform>` ", "返回数值服从范围[min, max)内均匀分布的随机 Tensor"

docs/api/paddle/Tensor_cn.rst

@@ -254,6 +254,34 @@ layout
 **代码示例**
 COPY-FROM: paddle.Tensor.layout
 
+requires_grad
+:::::::::
+
+查看一个 Tensor 是否计算并传播梯度。``requires_grad`` 属性与 ``stop_gradient`` 属性含义相反：
+
+- 当 ``requires_grad`` 为 ``True`` 时，该 Tensor 会计算梯度并参与梯度传播
+- 当 ``requires_grad`` 为 ``False`` 时，该 Tensor 不会计算梯度，并会阻止 Autograd 的梯度传播
+
+用户自行创建的 Tensor，``requires_grad`` 默认为 ``False``；模型参数的 ``requires_grad`` 默认为 ``True``。
+
+**代码示例**
+
+.. code-block:: python
+
+    import paddle
+
+    x = paddle.to_tensor([[1, 2], [3, 4]], dtype='float32')
+    print("x.requires_grad:", x.requires_grad)
+    # x.requires_grad: False
+
+    x.stop_gradient = False
+    print("x.requires_grad:", x.requires_grad)
+    # x.requires_grad: True
+
+    linear = paddle.nn.Linear(2, 1)
+    print("weight.requires_grad:", linear.weight.requires_grad)
+    # weight.requires_grad: True
+
 shape
 :::::::::
 

docs/api/paddle/mean_cn.rst

@@ -3,22 +3,27 @@
 mean
 -------------------------------
 
-.. py:function:: paddle.mean(x, axis=None, keepdim=False, name=None)
-
-
+.. py:function:: paddle.mean(x, axis=None, keepdim=False, name=None, *, dtype=None, out=None)
 
 沿参数 ``axis`` 计算 ``x`` 的平均值。
 
+.. note::
+    别名支持: 参数名 ``input`` 可替代 ``x`` 和 ``dim`` 可替代 ``axis``，如 ``input=tensor_x`` 等价于 ``x=tensor_x``， ``dim=0`` 等价于 ``axis=0``。
+
 参数
 ::::::::::
-    - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64。
+    - **x** (Tensor) - 输入的 Tensor，数据类型为：bool、bfloat16、float16、float32、float64、int32、int64、complex64、complex128。
+      ``别名：input``
     - **axis** (int|list|tuple，可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是 int、list(int)、tuple(int)。如果 ``axis`` 包含多个维度，则沿着 ``axis`` 中的所有轴进行计算。``axis`` 或者其中的元素值应该在范围[-D, D)内，D 是 ``x`` 的维度。如果 ``axis`` 或者其中的元素值小于 0，则等价于 :math:`axis + D`。如果 ``axis`` 是 None，则对 ``x`` 的全部元素计算平均值。默认值为 None。
+      ``别名：dim``
     - **keepdim** (bool，可选) - 是否在输出 Tensor 中保留减小的维度。如果 ``keepdim`` 为 True，则输出 Tensor 和 ``x`` 具有相同的维度(减少的维度除外，减少的维度的大小为 1)。否则，输出 Tensor 的形状会在 ``axis`` 上进行 squeeze 操作。默认值为 False。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+    - **dtype** (str，可选) - 输出 Tensor 的数据类型。如果指定了 ``dtype``，在计算之前输入 Tensor 会被转换为指定的类型。该参数为仅关键字参数，默认值为 None，此时输出的数据类型与输入 ``x`` 的数据类型一致。
+    - **out** (Tensor，可选)- 输出的结果。该参数为仅关键字参数，默认值为 None。
 
 返回
 ::::::::::
-    ``Tensor``，沿着 ``axis`` 进行平均值计算的结果，数据类型和 ``x`` 相同。
+    ``Tensor``，沿着 ``axis`` 进行平均值计算的结果，数据类型由 ``dtype`` 参数决定，如果 ``dtype`` 为 None 则与 ``x`` 相同。
 
 代码示例
 ::::::::::

docs/api/paddle/multinomial_cn.rst

@@ -3,7 +3,7 @@
 multinomial
 -------------------------------
 
-.. py:function:: paddle.multinomial(x, num_samples=1, replacement=False, name=None)
+.. py:function:: paddle.multinomial(x, num_samples=1, replacement=False, name=None, *, out=None)
 
 
 
@@ -12,13 +12,18 @@ multinomial
 输入 ``x`` 是用来随机采样的概率分布，``x`` 中每个元素都应该大于等于 0，且不能都为 0。
 参数 ``replacement`` 表示它是否是一个可放回的采样，如果 ``replacement`` 为 True，能重复对一种类别采样。
 
+.. note::
+    别名支持: 参数名 ``input`` 可替代 ``x``，如 ``input=tensor_x`` 等价于 ``x=tensor_x``。
+
 参数
 ::::::::::::
 
     - **x** (Tensor) - 输入的概率值。数据类型为 ``float32`` 、``float64`` 。
+      ``别名：input``
     - **num_samples** (int，可选) - 采样的次数（可选，默认值为 1）。
     - **replacement** (bool，可选) - 是否是可放回的采样（可选，默认值为 False）。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+    - **out** (Tensor，可选)- 输出的结果。该参数为仅关键字参数，默认值为 None。
 
 返回
 ::::::::::::

docs/api/paddle/rand_like.rst

@@ -0,0 +1,25 @@
+.. _cn_api_paddle_rand_like:
+
+rand_like
+-------------------------------
+
+.. py:function:: paddle.rand_like(input, name=None, *, dtype=None, device=None, requires_grad=False)
+
+返回一个与输入张量尺寸相同的张量，其元素为从区间 [0, 1) 上均匀分布中采样的随机数。
+
+参数
+::::::::::
+    - **input** (Tensor) – 输入的多维 Tensor，用于指定输出张量的形状。数据类型可以是 float16、bfloat16、float32、float64。
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+    - **dtype** (str|np.dtype|paddle.dtype，可选) - 输出 Tensor 的数据类型，支持 float16、bfloat16、float32、float64。当该参数值为 None 时，输出 Tensor 的数据类型与输入 Tensor 的数据类型一致。该参数为仅关键字参数，默认值为 None。
+    - **device** (str|paddle.Place，可选) - 指定创建 Tensor 的设备位置。如果为 None，则使用与输入 Tensor 相同的设备。该参数为仅关键字参数，默认值为 None。
+    - **requires_grad** (bool，可选) - 是否为创建的 Tensor 计算梯度。该参数为仅关键字参数，默认值为 False。
+
+返回
+::::::::::
+    Tensor：与输入张量 ``input`` 形状相同的 Tensor，其元素为从区间 [0, 1) 上均匀分布中采样的随机数，数据类型为 ``dtype``。
+
+代码示例
+:::::::::::
+
+COPY-FROM: paddle.rand_like

docs/api/paddle/var_cn.rst

@@ -3,7 +3,7 @@
 var
 -------------------------------
 
-.. py:function:: paddle.var(x, axis=None, unbiased=True, keepdim=False, name=None)
+.. py:function:: paddle.var(x, axis=None, unbiased=True, keepdim=False, name=None, *, correction=1, out=None)
 
 沿给定的轴 ``axis`` 计算 ``x`` 中元素的方差。
 
@@ -13,17 +13,19 @@ var
 参数
 ::::::::::
    - **x** (Tensor) - 输入的 Tensor，数据类型为：float16、float32、float64。
-   - **input** - ``x`` 的别名，行为完全一致。
+     ``别名：input``
    - **axis** (int|list|tuple，可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是 int、list(int)、tuple(int)。
+     ``别名：dim``
 
       - 如果 ``axis`` 包含多个维度，则沿着 ``axis`` 中的所有轴进行计算。``axis`` 或者其中的元素值应该在范围[-D, D)内，D 是 ``x`` 的维度。
       - 如果 ``axis`` 或者其中的元素值小于 0，则等价于 :math:`axis + D` 。
       - 如果 ``axis`` 是 None，则对 ``x`` 的全部元素计算方差。默认值为 None。
 
    - **unbiased** (bool，可选) - 是否使用无偏估计来计算方差。使用 :math:`N` 来代表在 axis 上的维度，如果 ``unbiased`` 为 True，则在计算中使用 :math:`N - 1` 作为除数。为 False 时将使用 :math:`N` 作为除数。默认值为 True。
    - **keepdim** (bool，可选) - 是否在输出 Tensor 中保留输入的维度。除非 keepdim 为 True，否则输出 Tensor 的维度将比输入 Tensor 小一维，默认值为 False。
-   - **dim** - ``axis`` 的别名，行为完全一致。
    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+   - **correction** (int|float，可选) - 样本数量与样本自由度之间的差异。该参数为仅关键字参数，默认值为 1（贝塞尔校正）。
+   - **out** (Tensor，可选)- 输出的结果。该参数为仅关键字参数，默认值为 None。
 
 返回
 ::::::::::