Added docs on paging and iteration.

docs/topics/overview.rst

@@ -9,4 +9,5 @@ Introductions to all the key parts of Cloudbridge you'll need to know:
     Connection and authentication setup <setup.rst>
     Launching instances <launch.rst>
     Object states and lifecycles <object_lifecycles.rst>
+    Paging and iteration <paging_and_iteration.rst>
     Using block storage <block_storage.rst>

docs/topics/paging_and_iteration.rst

@@ -0,0 +1,47 @@
+Paging and iteration
+====================
+
+Overview
+--------
+Most provider services have list() methods, and all list methods accept a limit
+parameter which specifies the maximum number of results to return. If a limit
+is not specified, cloudbridge will default to the global configuration variable
+`default_result_limit`, which can be modified through the provider config.
+
+Since the returned result list may have more records available, CloudBridge
+will always return a :py:class:`ResultList` object to assist with paging through
+additional results. A ResultList extends the standard :py:class:`list` and
+the following example illustrates how to fetch additional records.
+
+Example:
+
+.. code-block:: python
+
+    # get first page of results
+    rl = provider.compute.instances.list(limit=50)
+    for result in rl:
+        print("Instance Data: {0}", result)
+    if rl.supports_total:
+        print("Total results: {0}".format(rl.total_results))
+    else:
+        print("Total records unknown,"
+              "but has more data?: {0}."format(rl.is_truncated))
+
+    # Page to next set of results
+    if (rl.is_truncated)
+        rl = provider.compute.instances.list(limit=100,
+                                             marker=rl.marker)
+"""
+
+To ease development, CloudBridge also provides standard Python iterators that will page
+the results in for you automatically. Therefore, when you need to iterate through all
+available objects, the following shorthand is recommended:
+
+Example:
+
+.. code-block:: python
+
+    # Iterate through all results
+    for instance in provider.compute.instances:
+        print("Instance Data: {0}", instance)
+"""