From 77c288cce7b952c1dc5d534857b98771ed675e96 Mon Sep 17 00:00:00 2001
From: zhongpu <2013000149@qq.com>
Date: Thu, 5 Dec 2019 21:08:12 +0800
Subject: [PATCH] update gradient comment in Variable API, test=develop (#1625)
 (#1646)

* update gradient comment in Variable API, test=develop

* add sample code for Variable's gradient api, test=develop
---
 doc/fluid/api_cn/fluid_cn/Variable_cn.rst | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/doc/fluid/api_cn/fluid_cn/Variable_cn.rst b/doc/fluid/api_cn/fluid_cn/Variable_cn.rst
index d3fc780ae..70b1e0b62 100644
--- a/doc/fluid/api_cn/fluid_cn/Variable_cn.rst
+++ b/doc/fluid/api_cn/fluid_cn/Variable_cn.rst
@@ -178,9 +178,9 @@ Variable
 
 获取该 :ref:`api_guide_Variable` 的梯度值
 
-返回：该 :ref:`api_guide_Variable` 的梯度 ``ndarray`` 值
+返回：如果 :ref:`api_guide_Variable` 的类型是LoDTensor（参见 :ref:`cn_user_guide_lod_tensor` ），返回该 :ref:`api_guide_Variable` 类型为 ``ndarray`` 的梯度值；如果 :ref:`api_guide_Variable` 的类型是SelectedRows，返回该 :ref:`api_guide_Variable` 类型为 ``ndarray`` 的梯度值和类型为 ``ndarray`` 的词id组成的tuple。
 
-返回类型：``ndarray``
+返回类型：``ndarray`` 或者 ``tuple of ndarray`` , 返回类型 ``tuple of ndarray`` 仅在 :ref:`cn_api_fluid_dygraph_Embedding` 层稀疏更新时产生。
 
 
 **示例代码**
@@ -189,6 +189,7 @@ Variable
         import paddle.fluid as fluid
         import numpy as np
 
+        # example1: 返回ndarray
         x = np.ones([2, 2], np.float32)
         with fluid.dygraph.guard():
             inputs2 = []
@@ -203,6 +204,20 @@ Variable
             loss2.backward(backward_strategy)
             print(loss2.gradient())
 
+        # example2: 返回tuple of ndarray
+        with fluid.dygraph.guard():
+            embedding = fluid.dygraph.Embedding(
+                name_scope='embedding',
+                size=[20, 32],
+                param_attr='emb.w',
+                is_sparse=True)
+            x_data = np.arange(12).reshape(4, 3).astype('int64')
+            x_data = x_data.reshape((-1, 3, 1))
+            x = fluid.dygraph.base.to_variable(x_data)
+            out = embedding(x)
+            out.backward()
+            print(embedding._w.gradient())
+
 .. py:method:: clear_gradient()
 
 **注意：**
@@ -396,4 +411,4 @@ Variable
 
 **注意：该属性是只读属性**
 
-此 :ref:`api_guide_Variable` 的内存模型，例如是：:ref:`api_fluid_LoDTensor`， 或者SelectedRows
\ No newline at end of file
+此 :ref:`api_guide_Variable` 的内存模型，例如是：:ref:`api_fluid_LoDTensor`， 或者SelectedRows
-- 
GitLab