refine docs of CUDA and CPU places (#1269)

* refine docs of CUDA and CPU places, test=develop

* refine docs of CUDA and CPU places, test=develop

* refine cuda_pinned_places, test=develop

* refine, test=develop

* refine, test=develop

doc/fluid/api_cn/fluid_cn/CPUPlace_cn.rst

@@ -5,8 +5,7 @@ CPUPlace
 
 .. py:class:: paddle.fluid.CPUPlace
 
-
-CPUPlace是设备的描述符。它代表一个CPU，可以访问CPUPlace对应的内存。
+``CPUPlace`` 是一个设备描述符，表示一个分配或将要分配 ``Tensor`` 或 ``LoDTensor`` 的 ``CPU`` 设备。
 
 **代码示例**
 

doc/fluid/api_cn/fluid_cn/CUDAPinnedPlace_cn.rst

@@ -5,7 +5,8 @@ CUDAPinnedPlace
 
 .. py:class:: paddle.fluid.CUDAPinnedPlace
 
-CUDAPinnedPlace是一个设备描述符，它所指代的存储空间可以被GPU和CPU访问。
+``CUDAPinnedPlace`` 是一个设备描述符，它所指代的页锁定内存由 CUDA 函数 ``cudaHostAlloc()`` 在主机内存上分配，主机的操作系统将不会对这块内存进行分页和交换操作，可以通过直接内存访问技术访问，加速主机和 GPU 之间的数据拷贝。
+有关 CUDA 的数据转移和 ``pinned memory``，参见 `官方文档 <https://docs.nvidia.com/cuda/cuda-c-best-practices-guide/index.html#pinned-memory>`_ 。
 
 **代码示例**
 

doc/fluid/api_cn/fluid_cn/CUDAPlace_cn.rst

@@ -5,7 +5,17 @@ CUDAPlace
 
 .. py:class:: paddle.fluid.CUDAPlace
 
-CUDAPlace是一个设备描述符，它代表一个GPU，并且每个CUDAPlace有一个dev_id（设备id）来表明当前CUDAPlace代表的卡数。dev_id不同的CUDAPlace所对应的内存不可相互访问。
+<font color="#FF0000">**注意：多卡任务请先使用 FLAGS_selected_gpus 环境变量设置可见的GPU设备，下个版本将会修正 CUDA_VISIBLE_DEVICES 环境变量无效的问题。 **</font> 
+
+``CUDAPlace`` 是一个设备描述符，表示一个分配或将要分配 ``Tensor`` 或 ``LoDTensor`` 的 GPU 设备。
+每个 ``CUDAPlace`` 有一个 ``dev_id`` （设备id）来表明当前的 ``CUDAPlace`` 所代表的显卡编号，编号从 0 开始。
+``dev_id`` 不同的 ``CUDAPlace`` 所对应的内存不可相互访问。
+这里编号指的是可见显卡的逻辑编号，而不是显卡实际的编号。
+可以通过 ``CUDA_VISIBLE_DEVICES`` 环境变量限制程序能够使用的 GPU 设备，程序启动时会遍历当前的可见设备，并从 0 开始为这些设备编号。
+如果没有设置 ``CUDA_VISIBLE_DEVICES``，则默认所有的设备都是可见的，此时逻辑编号与实际编号是相同的。
+
+参数：
+  - **id** (int，可选) - GPU的设备ID。如果为 ``None``，则默认会使用 id 为 0 的设备。默认值为 ``None``。
 
 **代码示例**
 

doc/fluid/api_cn/fluid_cn/cpu_places_cn.rst

@@ -5,22 +5,22 @@ cpu_places
 
 .. py:function:: paddle.fluid.cpu_places(device_count=None)
 
-创建 ``fluid.CPUPlace`` 对象列表。
+该接口创建 ``device_count`` 个 ``fluid.CPUPlace`` 对象，并返回所创建的对象列表。
 
-如果 ``device_count`` 为None，则设备数目将由环境变量 ``CPU_NUM`` 确定。如果未设置 ``CPU_NUM`` ，则设备数目默认为1，也就是说， ``CPU_NUM`` =1。
+如果 ``device_count`` 为 ``None``，则设备数目将由环境变量 ``CPU_NUM`` 确定。如果未设置 ``CPU_NUM`` 环境变量，则设备数目会默认设为1，也就是说， ``CPU_NUM=1``。
+``CPU_NUM`` 表示在当前任务中使用的设备数目。如果 ``CPU_NUM`` 与物理核心数相同，可以加速程序的运行。
 
 参数：
-  - **device_count** (None|int) - 设备数目
+  - **device_count** (int，可选) - 设备数目。默认值为 ``None``。
 
-返回: CPUPlace列表
+返回: ``CPUPlace`` 的列表。
 
-返回类型：out (list(fluid.CPUPlace))
+返回类型：list[fluid.CPUPlace]
 
 **代码示例**
 
 .. code-block:: python
 
-           import paddle.fluid as fluid
-           cpu_places = fluid.cpu_places()
-
+      import paddle.fluid as fluid
+      cpu_places = fluid.cpu_places()
 

doc/fluid/api_cn/fluid_cn/cuda_pinned_places_cn.rst

@@ -8,16 +8,17 @@ cuda_pinned_places
 
 
 
-创建 ``fluid.CUDAPinnedPlace`` 对象列表。
+该接口创建 ``device_count`` 个 ``fluid.CUDAPinnedPlace`` 对象，并返回所创建的对象列表。
 
-如果 ``device_count`` 为None，则设备数目将由环境变量 ``CPU_NUM`` 确定。如果未设置 ``CPU_NUM`` ，则设备数目将由 ``multiprocessing.cpu_count()`` 确定。
+如果 ``device_count`` 为 ``None``，则设备数目将由环境变量 ``CPU_NUM`` 确定。如果未设置 ``CPU_NUM`` 环境变量，则设备数目会默认设为1，也就是说， ``CPU_NUM=1``。
+``CPU_NUM`` 表示在当前任务中使用的设备数目。如果 ``CPU_NUM`` 与物理核心数相同，可以加速程序的运行。
 
 参数：
-  - **device_count** (None|int) - 设备数目
+  - **device_count** (int，可选) - 设备数目。默认值为 ``None``。
 
-返回: CUDAPinnedPlace对象列表
+返回: ``fluid.CUDAPinnedPlace`` 对象列表。
 
-返回类型：out(list(fluid.CUDAPinnedPlace))
+返回类型：list[fluid.CUDAPinnedPlace]
 
 **代码示例**
 

doc/fluid/api_cn/fluid_cn/cuda_places_cn.rst

@@ -5,21 +5,23 @@ cuda_places
 
 .. py:function:: paddle.fluid.cuda_places(device_ids=None)
 
-创建 ``fluid.CUDAPlace`` 对象列表。
+<font color="#FF0000">**注意：多卡任务请先使用 FLAGS_selected_gpus 环境变量设置可见的GPU设备，下个版本将会修正 CUDA_VISIBLE_DEVICES 环境变量无效的问题。 **</font> 
 
+该接口根据 ``device_ids`` 创建一个或多个 ``fluid.CUDAPlace`` 对象，并返回所创建的对象列表。
 
+如果 ``device_ids`` 为 ``None``，则首先检查 ``FLAGS_selected_gpus`` 标志。
+例如： ``FLAGS_selected_gpus=0,1,2`` ，则返回的列表将为 ``[fluid.CUDAPlace(0), fluid.CUDAPlace(1), fluid.CUDAPlace(2)]``。
+如果未设置标志 ``FLAGS_selected_gpus`` ，则根据 ``CUDA_VISIBLE_DEVICES`` 环境变量，返回所有可见的 GPU places。
 
-如果 ``device_ids`` 为None，则首先检查 ``FLAGS_selected_gpus`` 的环境变量。如果 ``FLAGS_selected_gpus=0,1,2`` ，则返回的列表将为[fluid.CUDAPlace(0), fluid.CUDAPlace(1), fluid.CUDAPlace(2)]。如果未设置标志 ``FLAGS_selected_gpus`` ，则将返回所有可见的GPU places。
-
-
-如果 ``device_ids`` 不是None，它应该是GPU的设备ID。例如，如果 ``device_id=[0,1,2]`` ，返回的列表将是[fluid.CUDAPlace(0), fluid.CUDAPlace(1), fluid.CUDAPlace(2)]。
+如果 ``device_ids`` 不是 ``None``，它应该是使用的GPU设备ID的列表或元组。
+例如： ``device_id=[0,1,2]`` ，返回的列表将是 ``[fluid.CUDAPlace(0), fluid.CUDAPlace(1), fluid.CUDAPlace(2)]``。
 
 参数：
-  - **device_ids** (None|list(int)|tuple(int)) - GPU的设备ID列表
+  - **device_ids** (list(int)|tuple(int)，可选) - GPU的设备ID列表或元组。默认值为 ``None``。
 
-返回: CUDAPlace列表
+返回: 创建的 ``fluid.CUDAPlace`` 列表。
 
-返回类型：out (list(fluid.CUDAPlace))
+返回类型：list[fluid.CUDAPlace]
 
 **代码示例**