Rewrite firstn and shuffle functions (#1297)

* Rewrite firstn and shuffle functions, test=develop

doc/fluid/api_cn/data/data_reader_cn/Reader_cn.rst

@@ -105,34 +105,58 @@ Data Reader Interface
 
 .. py:function:: paddle.reader.shuffle(reader, buf_size)
 
-创建数据读取器，该reader的数据输出将被无序排列。
+**注意:paddle.reader.shuffle是paddle.fluid.io.shuffle的别名，推荐使用paddle.fluid.io.shuffle。**
+
+该接口创建一个数据读取器，其功能是将原始数据读取器的数据打乱，然后返回无序的数据。
+
+从原始数据读取器取出buf_size个数据到缓冲区，将缓冲区数据打乱，然后将无序的数据依次返回。当缓冲区数据全部输出后，再次执行上述步骤。
 
-由原始reader创建的迭代器的输出将被缓冲到shuffle缓冲区，然后进行打乱。打乱缓冲区的大小由参数buf_size决定。
 
 参数：
-    - **reader** (callable)  – 输出会被打乱的原始reader
-    - **buf_size** (int)  – 打乱缓冲器的大小
+    - **reader** (callable)  – 原始数据读取器。
+    - **buf_size** (int)  – 缓冲区保存数据的个数。
 
-返回： 输出会被打乱的reader
+返回： 返回无序数据的数据读取器
 
 返回类型： callable
 
+..  code-block:: python
+
+    import paddle
+    def reader():
+        for i in range(5):
+            yield i
+    shuffled_reader = paddle.reader.shuffle(reader, 3)
+    for e in shuffled_reader():
+        print(e)
+    # 输出结果是0~4的无序排列
 
 
 .. py:function:: paddle.reader.firstn(reader, n)
 
-限制reader可以返回的最大样本数。
+**注意:paddle.reader.firstn是paddle.fluid.io.firstn的别名，推荐使用paddle.fluid.io.firstn。**
+
+该接口创建一个数据读取器，它可以返回的最大样本数为n。
+
 
 参数：
-    - **reader** (callable)  – 要读取的数据读取器。
-    - **n** (int)  – 返回的最大样本数 。
+    - **reader** (callable)  – 输入的数据读取器。
+    - **n** (int)  – 可以返回的最大样本数。
 
-返回： 装饰reader
+返回： 新的的数据读取器。
 
 返回类型： callable
 
+..  code-block:: python
 
-
+    import paddle
+    def reader():
+        for i in range(100):
+            yield i
+    firstn_reader = paddle.reader.firstn(reader, 5)
+    for e in firstn_reader():
+        print(e)
+    # 输出结果为:0 1 2 3 4 
 
 .. py:function:: paddle.reader.xmap_readers(mapper, reader, process_num, buffer_size, order=False)
 

doc/fluid/api_cn/io_cn/firstn_cn.rst

@@ -5,12 +5,23 @@ firstn
 
 .. py:function:: paddle.fluid.io.firstn(reader, n)
 
-限制reader可以返回的最大样本数。
+该接口创建一个数据读取器，它可以返回的最大样本数为n。
 
 参数：
-    - **reader** (callable)  – 要读取的数据读取器。
-    - **n** (int)  – 返回的最大样本数 。
+    - **reader** (callable)  – 输入的数据读取器。
+    - **n** (int)  – 可以返回的最大样本数。
 
-返回： 装饰reader
+返回： 新的的数据读取器。
 
-返回类型： callable
\ No newline at end of file
+返回类型： callable
+
+..  code-block:: python
+
+    import paddle.fluid as fluid
+    def reader():
+        for i in range(100):
+            yield i
+    firstn_reader = fluid.io.firstn(reader, 5)
+    for e in firstn_reader():
+        print(e)
+    # 输出结果为:0 1 2 3 4

doc/fluid/api_cn/io_cn/shuffle_cn.rst

@@ -5,36 +5,25 @@ shuffle
 
 .. py:function:: paddle.fluid.io.shuffle(reader, buffer_size)
 
-创建一个特殊的数据读取器，它的输出数据会被重洗(shuffle)。由原始读取器创建的迭代器得到的输出将会被暂存到shuffle缓存区，其后
-会对其进行重洗运算。shuffle缓存区的大小由参数 ``buffer_size`` 决定。
+该接口创建一个数据读取器，其功能是将原始数据读取器的数据打乱，然后返回无序的数据。
 
-参数:
-    - **reader** (callable) – 输出会被shuffle的原始reader
-    - **buffer_size** (int) – 进行shuffle的buffer的大小
+从原始数据读取器取出buf_size个数据到缓冲区，将缓冲区数据打乱，然后将无序的数据依次返回。当缓冲区数据全部输出后，再次执行上述步骤。
 
-返回:其输出会被shuffle的一个reader（读取器）
+参数：
+    - **reader** (callable)  – 原始数据读取器。
+    - **buf_size** (int)  – 缓冲区保存数据的个数。
 
-返回类型:callable
+返回： 返回无序数据的数据读取器
 
-**代码示例**：
+返回类型： callable
 
-.. code-block:: python
+..  code-block:: python
 
     import paddle.fluid as fluid
-    raw_reader = fluid.layers.io.open_files(filenames=['./data1.recordio',
-                                                   './data2.recordio'],
-                                            shapes=[(3,224,224), (1,)],
-                                            lod_levels=[0, 0],
-                                            dtypes=['float32', 'int64'],
-                                            thread_num=2,
-                                            buffer_size=2)
-    batch_reader = fluid.layers.batch(reader=raw_reader, batch_size=5)
-    shuffle_reader = fluid.io.shuffle(reader=batch_reader, buffer_size=5000)
-
-
-
-
-
-
-
-
+    def reader():
+        for i in range(5):
+            yield i
+    shuffled_reader = fluid.io.shuffle(reader, 3)
+    for e in shuffled_reader():
+        print(e)
+    # 输出结果是0~4的无序排列