From ce1b25cc8b16fb02ef429366e1258075148f987e Mon Sep 17 00:00:00 2001
From: Yiqun Liu <liuyiqun01@baidu.com>
Date: Sat, 12 Oct 2019 13:52:52 +0800
Subject: [PATCH] Polish the English documentation of sums (#20495)

* Refine the documentation of sums.

* Remove Chinese comments and update API.spec.

* Refine the description of input argument.

* Update API.spec.
test=develop
test=document_fix
---
 paddle/fluid/API.spec                |  2 +-
 python/paddle/fluid/layers/tensor.py | 61 +++++++++++++++++-----------
 2 files changed, 39 insertions(+), 24 deletions(-)

diff --git a/paddle/fluid/API.spec b/paddle/fluid/API.spec
index bc98960ffb4..5390d754592 100644
--- a/paddle/fluid/API.spec
+++ b/paddle/fluid/API.spec
@@ -322,7 +322,7 @@ paddle.fluid.layers.create_global_var (ArgSpec(args=['shape', 'value', 'dtype',
 paddle.fluid.layers.cast (ArgSpec(args=['x', 'dtype'], varargs=None, keywords=None, defaults=None), ('document', '45df178cbd8c302f92c30ebdaaa6fa8a'))
 paddle.fluid.layers.tensor_array_to_tensor (ArgSpec(args=['input', 'axis', 'name', 'use_stack'], varargs=None, keywords=None, defaults=(1, None, False)), ('document', '4aa82374218ccf593bb8011df79c71e3'))
 paddle.fluid.layers.concat (ArgSpec(args=['input', 'axis', 'name'], varargs=None, keywords=None, defaults=(0, None)), ('document', 'ec7d6e716fb29ef1e73e1e3efa5ca46b'))
-paddle.fluid.layers.sums (ArgSpec(args=['input', 'out'], varargs=None, keywords=None, defaults=(None,)), ('document', '5df743d578638cd2bbb9369499b44af4'))
+paddle.fluid.layers.sums (ArgSpec(args=['input', 'out'], varargs=None, keywords=None, defaults=(None,)), ('document', '191164436efbc1b7bccc4190a88e7de2'))
 paddle.fluid.layers.assign (ArgSpec(args=['input', 'output'], varargs=None, keywords=None, defaults=(None,)), ('document', '98ce6e7c3659b8377c04cecfc72c2000'))
 paddle.fluid.layers.fill_constant_batch_size_like (ArgSpec(args=['input', 'shape', 'dtype', 'value', 'input_dim_idx', 'output_dim_idx', 'force_cpu'], varargs=None, keywords=None, defaults=(0, 0, False)), ('document', '2bb57637664173fee5f654e55896aec6'))
 paddle.fluid.layers.fill_constant (ArgSpec(args=['shape', 'dtype', 'value', 'force_cpu', 'out'], varargs=None, keywords=None, defaults=(False, None)), ('document', '66e1e468666dd47e5b2715226cebeac0'))
diff --git a/python/paddle/fluid/layers/tensor.py b/python/paddle/fluid/layers/tensor.py
index e7479c5bbae..806149b5b25 100644
--- a/python/paddle/fluid/layers/tensor.py
+++ b/python/paddle/fluid/layers/tensor.py
@@ -368,38 +368,53 @@ def tensor_array_to_tensor(input, axis=1, name=None, use_stack=False):
 
 def sums(input, out=None):
     """
-    This function performs the sum operation on the input and returns the
-    result as the output.
+    This function computes the sum of multiple input Tensors elementwisely.
+
+    - Case 1, sum of 3 Tensors
+
+    .. code-block:: text
+
+        # Input Tensors
+        x0.shape = [2, 3]
+        x0.data = [[1., 2., 3.],
+                   [4., 5., 6.]]
+        x1.shape = [2, 3]
+        x1.data = [[10., 20., 30.],
+                   [40., 50., 60.]]
+        x2.shape = [2, 3]
+        x2.data = [[100., 200., 300.],
+                   [400., 500., 600.]]
+
+        # Output Tensor
+        out.shape = [2, 3]
+        out.data = [[111., 222., 333.],
+                    [444., 555., 666.]]
 
     Args:
-        input (Variable|list): The input tensor that has the elements
-                               that need to be summed up.
-        out (Variable|None): Output parameter. The sum result.
-                             Default: None
+        input (list): A list of Variables which hold input Tensors with the same
+            data type and shape. Optional data types are: float32, float64, int32, int64.
+        out (Variable, optional): Output Tensor. It can be any existing Variable.
+            The default value is None, then a new Variable will be created and returned.
 
     Returns:
-        Variable: the sum of input. The same as the argument 'out'
+        Variable: The sum of inputs. The shape and data type is the same with input. \
+            If :code:`out` is not None, the returned value is :code:`out` .
 
     Examples:
         .. code-block:: python
 
-          import paddle.fluid as fluid
+            import paddle.fluid as fluid
+
+            x0 = fluid.layers.fill_constant(shape=[16, 32], dtype='int64', value=1)
+            x1 = fluid.layers.fill_constant(shape=[16, 32], dtype='int64', value=2)
+            x2 = fluid.layers.fill_constant(shape=[16, 32], dtype='int64', value=3)
+            x3 = fluid.layers.fill_constant(shape=[16, 32], dtype='int64', value=0)
+
+            # Sum of multiple Tensors, the result is stored to a new Variable sum0 (sum0=x0+x1+x2, the value is [[6, ..., 6], ..., [6, ..., 6]])
+            sum0 = fluid.layers.sums(input=[x0, x1, x2])
 
-          # sum of several tensors
-          a0 = fluid.layers.fill_constant(shape=[1], dtype='int64', value=1)
-          a1 = fluid.layers.fill_constant(shape=[1], dtype='int64', value=2)
-          a2 = fluid.layers.fill_constant(shape=[1], dtype='int64', value=3)
-          sums = fluid.layers.sums(input=[a0, a1, a2])
-
-          # sum of a tensor array
-          array = fluid.layers.create_array('int64')
-          i = fluid.layers.zeros(shape=[1], dtype='int64', force_cpu=True)
-          fluid.layers.array_write(a0, array=array, i=i)
-          i = fluid.layers.increment(x=i)
-          fluid.layers.array_write(a1, array=array, i=i)
-          i = fluid.layers.increment(x=i)
-          fluid.layers.array_write(a2, array=array, i=i)
-          sums = fluid.layers.sums(input=array)
+            # Sum of multiple Tensors, sum1 and x3 represents the same Variable (x3=x0+x1+x2, the value is [[6, ..., 6], ..., [6, ..., 6]])
+            sum1 = fluid.layers.sums(input=[x0, x1, x2], out=x3)
     """
     helper = LayerHelper('sum', **locals())
     if out is None:
-- 
GitLab