add deprecated for gather api and refine the doc of gather api

python/paddle/fluid/layers/nn.py

@@ -8207,9 +8207,9 @@ def image_resize_short(input, out_short_len, resample='BILINEAR'):
     return image_resize(input=input, out_shape=out_shape, resample=resample)
 
 
+@deprecated(since="2.0.0", update_to="paddle.gather")
 def gather(input, index, overwrite=True):
     """
-    **Gather Layer**
 
     Output is obtained by gathering entries of the outer-most dimension
     of X indexed by `index` and concatenate them together.
@@ -8280,6 +8280,7 @@ def gather(input, index, overwrite=True):
     return out
 
 
+@deprecated(since="2.0.0", update_to="paddle.gather_nd")
 def gather_nd(input, index, name=None):
     """
     **Gather Nd Layer**
@@ -8332,7 +8333,7 @@ def gather_nd(input, index, name=None):
                          = [23]
 
     Args:
-        input (Tensor): The source input. Its dtype should be bool, float32, float64, int32, int64.
+        input (Tensor): The input Tensor which it's data typeshould be bool, float32, float64, int32, int64.
         index (Tensor): The index input with rank > 1, index.shape[-1] <= input.rank.
                         Its dtype should be int32, int64.
         name(str, optional): The default value is None.  Normally there is no need for user to set this property.

python/paddle/tensor/manipulation.py

@@ -30,7 +30,6 @@
 from ..fluid.layers import unique  #DEFINE_ALIAS
 from ..fluid.layers import unstack  #DEFINE_ALIAS
 
-from ..fluid.layers import gather_nd  #DEFINE_ALIAS
 from ..fluid.layers import scatter_nd_add  #DEFINE_ALIAS
 from ..fluid.layers import scatter_nd  #DEFINE_ALIAS
 from ..fluid.layers import shard_index  #DEFINE_ALIAS
@@ -663,13 +662,8 @@ def gather(x, index, axis=None, name=None):
 
     **Gather Layer**
 
-    Output is obtained by gathering entries of the outer-most dimension
-    of X indexed by `index` and concatenate them together.
-
-    .. math::
-
-        Out = X[Index]
-
+    Output is obtained by gathering entries of ``axis``
+    of ``x`` indexed by ``index`` and concatenate them together.
 
     .. code-block:: text
 
@@ -692,7 +686,7 @@ def gather(x, index, axis=None, name=None):
             int32, int64, float32, float64 and uint8 (only for CPU),
             float16 (only for GPU).
         index (Tensor): The index input tensor with rank=1. Data type is int32 or int64.
-        axis (Tensor|int, optional): The axis of input to be gathered, it's can be int or a Tensor with data type is int32 or int64. Default: if None, the axis is 0.
+        axis (Tensor|int, optional): The axis of input to be gathered, it's can be int or a Tensor with data type is int32 or int64. The default value is None, if None, the ``axis`` is 0.
         name (str, optional): The default value is None.  Normally there is no need for user to set this property.
             For more information, please refer to :ref:`api_guide_Name` .
 
@@ -1242,7 +1236,6 @@ def reshape(x, shape, name=None):
 
 def gather_nd(x, index, name=None):
     """
-    **Gather Nd Layer**
 
     This function is actually a high-dimensional extension of :code:`gather`
     and supports for simultaneous indexing by multiple axes. :attr:`index` is a
@@ -1260,35 +1253,35 @@ def gather_nd(x, index, name=None):
     .. code-block:: text
 
             Given:
-                input = [[[ 0,  1,  2,  3],
+                x = [[[ 0,  1,  2,  3],
                           [ 4,  5,  6,  7],
                           [ 8,  9, 10, 11]],
                          [[12, 13, 14, 15],
                           [16, 17, 18, 19],
                           [20, 21, 22, 23]]]
-                input.shape = (2, 3, 4)
+                x.shape = (2, 3, 4)
 
             * Case 1:
                 index = [[1]]
 
-                gather_nd(input, index)
-                         = [input[1, :, :]]
+                gather_nd(x, index)
+                         = [x[1, :, :]]
                          = [[12, 13, 14, 15],
                             [16, 17, 18, 19],
                             [20, 21, 22, 23]]
 
             * Case 2:
                 index = [[0,2]]
 
-                gather_nd(input, index)
-                         = [input[0, 2, :]]
+                gather_nd(x, index)
+                         = [x[0, 2, :]]
                          = [8, 9, 10, 11]
 
             * Case 3:
                 index = [[1, 2, 3]]
 
-                gather_nd(input, index)
-                         = [input[1, 2, 3]]
+                gather_nd(x, index)
+                         = [x[1, 2, 3]]
                          = [23]
 
     Args:
@@ -1308,6 +1301,7 @@ def gather_nd(x, index, name=None):
     Examples:
 
         .. code-block:: python
+
             import paddle
             import numpy as np