chrypk pr582 to 1.2 (#588)

* 0123-routine-docbug-fix

* Update metrics.rst

doc/fluid/api_cn/layers_cn.rst

@@ -1226,6 +1226,8 @@ reader也是变量。可以为由fluid.layers.open_files()生成的原始reader
 
 返回：从给定的reader中读取数据
 
+返回类型: tuple（元组）
+
 **代码示例**：
 
 .. code-block:: python
@@ -8447,12 +8449,12 @@ topk
         k = 2
 
     则:
-        第一个输入:
+        第一个输出:
         values = [[5, 4],
                 [10, 25],
                 [6, 10]]
 
-        第二个输入:
+        第二个输出:
         indices = [[0, 1],
                 [2, 3],
                 [0, 2]]

doc/fluid/user_guides/howto/evaluation_and_debugging/evaluation/metrics.rst

@@ -2,7 +2,7 @@
 模型评估
 ############
 
-模型评估是用指标反映模型在预期目标下精度，根据模型任务决定观察指标，作为在训练中调整超参数，评估模型效果的重要依据。
+模型评估是指用指标(metrics)反映模型在预期目标下的精度。其中，指标(metrics)根据模型任务决定。模型评估可作为在训练中调整超参数、评估模型效果的重要依据。
 metric函数的输入为当前模型的预测preds和labels，输出是自定义的。metric函数和loss函数非常相似，但是metric并不是模型训练网络组成部分。
 
 用户可以通过训练网络得到当前的预测preds和labels，在Python端定制metric函数；也可以通过定制c++ Operator的方式，在GPU上加速metric计算。
@@ -15,8 +15,8 @@ paddle.fluid.metrics模块包含该功能
 
 metric函数根据模型任务不同，指标构建方法因任务而异。
 
-回归类型任务labels是实数，因此loss和metric函数构建相同，可参考MSE的方法。
-分类任务常用指标为分类指标，本文提到的一般是二分类指标，多分类和多标签需要查看对应的API文档。例如排序指标auc，多分类可以作为0，1分类任务，auc指标仍然适用。
+回归类型任务labels是实数，可参考MSE(Mean Squared Error)的方法。
+分类任务常用指标为分类指标（classification metrics），本文提到的一般是二分类指标，多分类和多标签需要查看对应的API文档。例如排序指标auc，多分类可以作为0，1分类任务，auc指标仍然适用。
 Fluid中包含了常用分类指标，例如Precision, Recall, Accuracy等,更多请阅读API文档。以 :ref:`Precision` 为例，具体方法为
 
 .. code-block:: python

doc/fluid/user_guides/howto/training/cluster_quick_start.rst

@@ -150,12 +150,12 @@ DistributeTranspiler
         pservers = pserver_endpoints,    
         trainers = trainers)
     if PADDLE_TRAINING_ROLE == "TRAINER":
-        # fetch the pserver program and execute it
+        # fetch the trainer program and execute it
         trainer_prog = t.get_trainer_program()
         ...
 
     elif PADDLE_TRAINER_ROLE == "PSERVER":
-        # fetch the trainer program and execute it
+        # fetch the pserver program and execute it
         pserver_prog = t.get_pserver_program(current_endpoint) 
         ...
 

doc/fluid/user_guides/howto/training/save_load_variables.rst

@@ -7,19 +7,19 @@
 模型变量分类
 ############
 
-在PaddlePaddle Fluid中，所有的模型变量都用 :code:`fluid.Variable()` 作为基类进行表示。
+在PaddlePaddle Fluid中，所有的模型变量都用 :code:`fluid.framework.Variable()` 作为基类进行表示。
 在该基类之下，模型变量主要可以分为以下几种类别：
 
 1. 模型参数
   模型参数是深度学习模型中被训练和学习的变量，在训练过程中，训练框架根据反向传播算法计算出每一个模型参数当前的梯度，
   并用优化器根据梯度对参数进行更新。模型的训练过程本质上可以看做是模型参数不断迭代更新的过程。
   在PaddlePaddle Fluid中，模型参数用 :code:`fluid.framework.Parameter` 来表示，
-  这是一个 :code:`fluid.Variable()` 的派生类，除了 :code:`fluid.Variable()` 具有的各项性质以外，
+  这是一个 :code:`fluid.framework.Variable()` 的派生类，除了 :code:`fluid.framework.Variable()` 具有的各项性质以外，
   :code:`fluid.framework.Parameter` 还可以配置自身的初始化方法、更新率等属性。
 
 2. 长期变量
   长期变量指的是在整个训练过程中持续存在、不会因为一个迭代的结束而被销毁的变量，例如动态调节的全局学习率等。
-  在PaddlePaddle Fluid中，长期变量通过将 :code:`fluid.Variable()` 的 :code:`persistable`
+  在PaddlePaddle Fluid中，长期变量通过将 :code:`fluid.framework.Variable()` 的 :code:`persistable`
   属性设置为 :code:`True` 来表示。所有的模型参数都是长期变量，但并非所有的长期变量都是模型参数。
 
 3. 临时变量