api20, Bilinear add deprecated, and fix english doc (#26610)

* API2.0 del old api(BilinearTensorProduct) from nn init.py, test=develop

* add import for deprecated, test=develop

* modify deprecated location, test=develop

* fix english doc, test=develop

* Update __init__.py

* Update __init__.py

* Update common.py

* fix english doc, test=develop
Co-authored-by: NChen Weihang <chenweihang@baidu.com>

python/paddle/fluid/dygraph/nn.py

@@ -31,6 +31,7 @@ from ..data_feeder import check_variable_and_dtype, check_type
 import numpy as np
 import numbers
 import logging
+import paddle.utils.deprecated as deprecated
 
 __all__ = [
     'Conv2D', 'Conv3D', 'Pool2D', 'Linear', 'BatchNorm', 'Dropout', 'Embedding',
@@ -2445,6 +2446,10 @@ class BilinearTensorProduct(layers.Layer):
             dtype=self._dtype,
             is_bias=True)
 
+    @deprecated(
+        since="2.0.0",
+        update_to="paddle.nn.Bilinear",
+        reason="New name and new args in Bilinear, easier to use.")
     def forward(self, x, y):
         check_variable_and_dtype(x, 'x', ['float32', 'float64'],
                                  'BilinearTensorProduct')

python/paddle/nn/functional/common.py

@@ -467,18 +467,7 @@ def bilinear(x1, x2, weight, bias=None, name=None):
     """
 
     This layer performs bilinear on two inputs.
-
-    .. math::
-      out_{i} = x1 * W_{i} * {x2^\mathrm{T}}, i=0,1,...,size-1
-      out = out + b
-
-    In this formula:
-     - :math:`x1`: the first input contains in1_features elements, shape is [batch_size, in1_features].
-     - :math:`x2`: the second input contains in2_features elements, shape is [batch_size, in2_features].
-     - :math:`W_{i}`: the i-th learned weight, shape is [in1_features, in2_features], and learned weight's shape is [out_features, in1_features, in2_features].
-     - :math:`out_{i}`: the i-th element of out, shape is [batch_size, out_features].
-     - :math:`b`: the learned bias, shape is [1, out_features].
-     - :math:`x2^\mathrm{T}`: the transpose of :math:`x2`.
+    See :ref:`api_nn_Bilinear` for details and output shape.
 
     Parameters:
        x1 (Tensor): the first input tensor, it's data type should be float32, float64.
@@ -489,7 +478,7 @@ def bilinear(x1, x2, weight, bias=None, name=None):
            to set this property. For more information, please refer to :ref:`api_guide_Name`. Default: None.
 
     Returns:
-       Variable: A 2-D Tensor of shape [batch_size, out_features].
+       Tensor: A 2-D Tensor of shape [batch_size, out_features].
 
     Examples:
        .. code-block:: python

python/paddle/nn/layer/__init__.py

@@ -41,6 +41,7 @@ from .activation import Sigmoid  #DEFINE_ALIAS
 from .activation import LogSoftmax  #DEFINE_ALIAS
 from .activation import HSigmoid  #DEFINE_ALIAS
 from .common import BilinearTensorProduct  #DEFINE_ALIAS
+from .common import Bilinear  #DEFINE_ALIAS
 from .common import Pool2D  #DEFINE_ALIAS
 from .common import Pad2D  #DEFINE_ALIAS
 from .common import ReflectionPad1d  #DEFINE_ALIAS

python/paddle/nn/layer/common.py

@@ -360,7 +360,9 @@ class Bilinear(layers.Layer):
     This layer performs bilinear on two inputs.
 
     .. math::
+
       out_{i} = x1 * W_{i} * {x2^\mathrm{T}}, i=0,1,...,size-1
+
       out = out + b
 
     In this formula:
@@ -389,7 +391,7 @@ class Bilinear(layers.Layer):
         **bias** (Parameter): the learnable bias of this layer.
 
     Returns:
-       Variable: A 2-D Tensor of shape [batch_size, out_features].
+       Tensor: A 2-D Tensor of shape [batch_size, out_features].
 
     Examples:
        .. code-block:: python