improved documentation of freeze

dataset/freeze/app.py

@@ -21,10 +21,44 @@ parser.add_argument('config', metavar='CONFIG', type=str,
 def freeze(result, format='csv', filename='freeze.csv',
            prefix='.', meta={}, indent=2, mode='list', wrap=True, **kw):
     """
-    Perform a data export of a given SQL statement. This is a very
+    Perform a data export of a given result set. This is a very
     flexible exporter, allowing for various output formats, metadata
     assignment, and file name templating to dump each record (or a set
     of records) into individual files.
+
+    ::
+
+        result = db['person'].all()
+        dataset.freeze(result, format='json', filename='all-persons.json')
+
+
+    freeze supports two values for ``mode``:
+
+        *list* (default)
+            The entire result set is dumped into a single file.
+
+        *item*
+            One file is created for each row in the result set.
+
+    You should set a ``filename`` for the exported file(s). If ``mode``
+    is set to *item* the function would generate one file per row. In
+    that case you can  use values as placeholders in filenames::
+
+            dataset.freeze(res, mode='item', format='json', filename='item-{{id}}.json')
+
+    The following output ``format`` s are supported:
+
+        *csv*
+            Comma-separated values, first line contains column names.
+
+        *json*
+            A JSON file containing a list of dictionaries for each row
+            in the table.
+
+        *tabson*
+            Tabson is a smart combination of the space-efficiency of the
+            CSV and the parsability and structure of JSON.
+
     """
     kw.update({
         'format': format,