Documenting the fact the more_results is unfit for use in datastore.

Author: dhermes

gcloud/datastore/connection.py

@@ -217,12 +217,14 @@ def run_query(self, dataset_id, query_pb, namespace=None):
         Using the `fetch`` method...
 
         >>> query.fetch()
-        [<list of Entity Protobufs>], cursor, more_results, skipped_results
+        [<list of Entity unmarshalled from protobuf>]
+        >>> query.cursor()
+        <string containing cursor where fetch stopped>
 
         Under the hood this is doing...
 
         >>> connection.run_query('dataset-id', query.to_protobuf())
-        [<list of Entity Protobufs>]
+        [<list of Entity Protobufs>], cursor, more_results, skipped_results
 
         :type dataset_id: string
         :param dataset_id: The ID of the dataset over which to run the query.

gcloud/datastore/query.py

@@ -333,6 +333,13 @@ def fetch(self, limit=None):
             dataset_id=self.dataset().id(),
             namespace=self._namespace,
             )
+        # NOTE: `query_results` contains two extra values that we don't use,
+        #       namely `more_results` and `skipped_results`. The value of
+        #       `more_results` is unusable because it always returns an enum
+        #       value of MORE_RESULTS_AFTER_LIMIT even if there are no more
+        #       results. See
+        #       https://github.com/GoogleCloudPlatform/gcloud-python/issues/280
+        #       for discussion.
         entity_pbs, end_cursor = query_results[:2]
 
         self._cursor = end_cursor