Update the doc of save_vars and load_vars (#1251)

* update save_vars and load_vars, test=develop

doc/fluid/api_cn/io_cn/load_vars_cn.rst

@@ -5,24 +5,23 @@ load_vars
 
 .. py:function:: paddle.fluid.io.load_vars(executor, dirname, main_program=None, vars=None, predicate=None, filename=None)
 
-``executor`` 从指定目录加载变量。
+该接口从文件中加载 ``Program`` 的变量。
 
-有两种方法来加载变量:方法一，``vars`` 为变量的列表。方法二，将已存在的 ``Program`` 赋值给 ``main_program`` ，然后将加载 ``Program`` 中的所有变量。第一种方法优先级更高。如果指定了 vars，那么忽略 ``main_program`` 和 ``predicate`` 。
-
-``dirname`` 用于指定加载变量的目录。如果变量保存在指定目录的若干文件中，设置文件名 None; 如果所有变量保存在一个文件中，请使用 ``filename`` 来指定它。
+通过 ``vars`` 指定需要加载的变量，或者通过 ``predicate`` 筛选需要加载的变量， ``vars`` 和 ``predicate`` 不能同时为None。
 
 参数:
- - **executor**  (Executor) – 加载变量的 executor
- - **dirname**  (str) – 目录路径
- - **main_program**  (Program|None) – 需要加载变量的 Program。如果为 None，则使用 default_main_Program 。默认值: None
- - **vars**  (list[Variable]|None) –  要加载的变量的列表。 优先级高于main_program。默认值: None
- - **predicate**  (function|None) – 如果不等于None，当指定main_program， 那么只有 predicate(variable)==True 时，main_program中的变量会被加载。
- - **filename**  (str|None) – 保存变量的文件。如果想分开保存变量，设置 filename=None. 默认值: None
+ - **executor**  (Executor) – 运行的执行器，执行器的介绍请参考 :ref:`api_guide_model_save_reader` 。
+ - **dirname**  (str) – 加载变量所在的目录路径。
+ - **main_program**  (Program，可选) – 需要加载变量的 ``Program`` ， ``Program`` 的介绍请参考 :ref:`api_guide_Program` 。如果 ``main_program`` 为None，则使用默认的主程序。默认值为None。
+ - **vars**  (list[Variable]，可选) –  通过该列表指定需要加载的变量。默认值为None。
+ - **predicate**  (function，可选) – 通过该函数筛选 :math:`predicate(variable)== True` 的变量进行加载。如果通过 ``vars`` 指定了需要加载的变量，则该参数无效。默认值为None。
+ - **filename**  (str，可选) – 加载所有变量的文件。如果所有待加载变量是保存在一个文件中，则设置 ``filename`` 为该文件名；如果所有待加载变量是按照变量名称单独保存成文件，则设置 ``filename`` 为None。默认值为None。
+
+返回： 无
 
 抛出异常：
-  - ``TypeError`` - 如果参数 ``main_program`` 为 None 或为一个非 ``Program`` 的实例
-   
-返回: None
+  - ``TypeError`` - 如果main_program不是Program的实例，也不是None。
+ 
   
 **代码示例**
 
@@ -41,26 +40,26 @@ load_vars
     exe = fluid.Executor(place)
     exe.run(startup_prog)
 
-    param_path = "./my_paddle_model"
-
-    # 第一种使用方式 使用 main_program 指定变量
-    def name_has_fc(var):
-        res = "fc" in var.name
-        return res
-    fluid.io.save_vars(executor=exe, dirname=param_path, main_program=main_prog, vars=None, predicate=name_has_fc)
-    fluid.io.load_vars(executor=exe, dirname=param_path, main_program=main_prog, vars=None, predicate=name_has_fc)
-    #加载所有`main_program`中变量名包含 ‘fc’ 的变量
-    #并且此前所有变量应该保存在不同文件中
-
-    #用法2：使用 `vars` 来使变量具体化
+    # 示例一：用vars来指定加载变量。
     path = "./my_paddle_vars"
     var_list = [w, b]
     fluid.io.save_vars(executor=exe, dirname=path, vars=var_list,
                        filename="vars_file")
     fluid.io.load_vars(executor=exe, dirname=path, vars=var_list,
                        filename="vars_file")
-    # 加载w和b，它们此前应被保存在同一名为'var_file'的文件中
-    # 该文件所在路径为 "./my_paddle_model"
+    # 加载w和b。它们被保存在'var_file'的文件中，所在路径为 "./my_paddle_model" 。
+    
+    # 示例二：通过predicate来筛选加载变量。
+    def name_has_fc(var):
+        res = "fc" in var.name
+        return res
+    
+    param_path = "./my_paddle_model"
+    fluid.io.save_vars(executor=exe, dirname=param_path, main_program=main_prog, vars=None, predicate=name_has_fc)
+    fluid.io.load_vars(executor=exe, dirname=param_path, main_program=main_prog, vars=None, predicate=name_has_fc)
+    #加载 `main_program` 中变量名包含 ‘fc’ 的所有变量
+    #此前所有变量应该保存在不同文件中
+
  
 
 

doc/fluid/api_cn/io_cn/save_vars_cn.rst

@@ -5,23 +5,21 @@ save_vars
 
 .. py:function:: paddle.fluid.io.save_vars(executor, dirname, main_program=None, vars=None, predicate=None, filename=None)
 
-通过 ``Executor`` ,此函数将变量保存到指定目录下。
+该接口将 ``Program`` 的变量保存到文件中。
 
-有两种方法可以指定要保存的变量：第一种方法，在列表中列出变量并将其传给 ``vars`` 参数。第二种方法是，将现有程序分配给 ``main_program`` ，它会保存program中的所有变量。第一种方式具有更高的优先级。换句话说，如果分配了变量，则将忽略 ``main_program`` 和 ``predicate`` 。
-
-``dirname`` 用于指定保存变量的文件夹。如果您希望将变量分别保存在文件夹目录的多个单独文件中，请设置 ``filename`` 为无；如果您希望将所有变量保存在单个文件中，请使用 ``filename`` 指定它。
+通过 ``vars`` 指定需要保存的变量，或者通过 ``predicate`` 筛选需要保存的变量， ``vars`` 和 ``predicate`` 不能同时为None。
 
 参数：
-      - **executor** （Executor）- 为保存变量而运行的执行器。
-      - **dirname** （str）- 目录路径。
-      - **main_program** （Program | None）- 保存变量的程序。如果为None，将自动使用默认主程序。默认值：None。
-      - **vars** （list [Variable] | None）- 包含要保存的所有变量的列表。它的优先级高于 ``main_program`` 。默认值：None。
-      - **predicate** （function | None）- 如果它不是None，则只保存 ``main_program`` 中使 :math:`predicate(variable)== True` 的变量。它仅在我们使用 ``main_program`` 指定变量时才起作用（换句话说，vars为None）。默认值：None。
-      - **filename** （str | None）- 保存所有变量的文件。如果您希望单独保存变量，请将其设置为None。默认值：None。
+      - **executor** （Executor）- 运行的执行器，执行器的介绍请参考 :ref:`api_guide_model_save_reader` 。
+      - **dirname** （str）- 保存变量的目录路径。
+      - **main_program** （Program，可选）- 需要保存变量的 ``Program`` ， ``Program`` 的介绍请参考 :ref:`api_guide_Program` 。如果 ``main_program`` 为None，则使用默认的主程序。默认值为None。
+      - **vars** （list [Variable]，可选）- 通过该列表指定需要保存的变量。默认值为None。
+      - **predicate** （function，可选）- 通过该函数筛选 :math:`predicate(variable)== True` 的变量进行保存。如果通过 ``vars`` 指定了需要保存的变量，则该参数无效。默认值为None。
+      - **filename** （str，可选）- 保存所有变量的文件。如果设置为None，所有变量会按照变量名称单独保存成文件；如果设置为非None，所有变量会保存成一个文件名为该设置值的文件。默认值为None。
 
-返回：     None
+返回：无    
 
-抛出异常：    
+抛出异常：
     - ``TypeError`` - 如果main_program不是Program的实例，也不是None。
 
 **代码示例**
@@ -41,28 +39,24 @@ save_vars
       exe = fluid.Executor(place)
       exe.run(startup_prog)
      
-      param_path = "./my_paddle_model"
+      # 示例一：用vars来指定变量。
+      var_list = [w, b]
+      path = "./my_paddle_vars"
+      fluid.io.save_vars(executor=exe, dirname=path, vars=var_list,
+                         filename="vars_file")
+      # w, b 将被保存，使用同一文件名“var_file”，保存在路径“./my_paddle_vars”下。
 
-      # 第一种用法:用main_program来指定变量。
+      # 示例二：通过predicate筛选变量。
       def name_has_fc(var):
           res = "fc" in var.name
           return res
 
+      param_path = "./my_paddle_model"
       fluid.io.save_vars(executor=exe, dirname=param_path, main_program=main_prog, vars=None, predicate = name_has_fc)
       # 将main_program中名中包含“fc”的的所有变量保存。
       # 变量将分开保存。
 
 
-      # 第二种用法: 用vars来指定变量。
-      var_list = [w, b]
-      path = "./my_paddle_vars"
-      fluid.io.save_vars(executor=exe, dirname=path, vars=var_list,
-                         filename="vars_file")
-      # var_a，var_b和var_c将被保存。
-      #他们将使用同一文件，名为“var_file”，保存在路径“./my_paddle_vars”下。
-
-
-