1 files changed, 32 insertions, 0 deletions
diff --git a/pygithub3/core/result.py b/pygithub3/core/result.py
index 9e69e7d..5a2aa80 100644
--- a/pygithub3/core/result.py
+++ b/pygithub3/core/result.py
@@ -137,6 +137,38 @@ class Page(object):
 class Result(object):
     """
     Result is a very lazy paginator. It only do a real request when is needed
+
+    You have several ways to consume it
+
+    #. Iterating over the result::
+
+        result = some_request()
+        for page in result:
+            for resource in page:
+                print resource
+
+    #. With a generator::
+
+        result = some_request()
+        for resource in result.iterator():
+            print resource
+
+    #. As a list::
+
+        result = some_request()
+        print result.all()
+
+    #. Also you can request some page manually
+
+        .. autoattribute:: pygithub3.core.result.Result.pages
+        .. automethod:: pygithub3.core.result.Result.get_page
+
+        Each ``Page`` is an iterator and contains resources::
+
+            result = some_request()
+            assert result.pages > 3
+            page3 = result.get_page(3)
+            page3_resources = list(page3)
     """
 
     def __init__(self, client, request, **kwargs):