Add doc for 'batch'

python/paddle/fluid/layers/io.py

@@ -549,6 +549,41 @@ def shuffle(reader, buffer_size):
 
 
 def batch(reader, batch_size):
+    """
+    This layer is a reader decorator. It takes a reader and adds 
+    'batching' decoration on it. When reading with the result 
+    decorated reader, output data will be automatically organized 
+    to the form of batches.
+
+    Args:
+        reader(Variable): The reader to be decorated with 'batching'.
+        batch_size(int): The batch size.
+
+    Returns:
+        Variable: The reader which has been decorated with 'batching'.
+
+    Examples:
+        .. code-block:: python
+
+            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)
+
+            # If we read data with the raw_reader:
+            #     data = fluid.layers.read_file(raw_reader)
+            # We can only get data instance by instance.
+            # 
+            # However, if we read data with the batch_reader:
+            #     data = fluid.layers.read_file(batch_reader)
+            # Each 5 adjacent instances will be automatically combined together 
+            # to become a batch. So what we get('data') is a batch data instead 
+            # of an instance.
+    """
     return __create_unshared_decorated_reader__(
         'create_batch_reader', reader, {'batch_size': int(batch_size)})
 
@@ -571,20 +606,20 @@ def parallel(reader):
                                               {})
 
 
-def read_file(file_obj):
+def read_file(reader):
     """
-    Read data from a file object.
+    Execute the given reader and get data via it.
 
-    A file object is also a Variable. It can be a raw file object generated by 
+    A reader is also a Variable. It can be a raw reader generated by 
     `fluid.layers.open_files()` or a decorated one generated by 
     `fluid.layers.double_buffer()` and so on.
 
     Args:
 
-        file_obj(Variable): The file object from where to read data.
+        reader(Variable): The reader to execute.
 
     Returns:
-        Tuple[Variable]: Data read from the given file object.
+        Tuple[Variable]: Data read via the given reader.
 
     Examples:
         .. code-block:: python