docs: clarify list_blobs usage (#866)

Author: cojenco

google/cloud/storage/client.py

@@ -1269,7 +1269,8 @@ def list_blobs(
 
         Returns:
             Iterator of all :class:`~google.cloud.storage.blob.Blob`
-            in this bucket matching the arguments.
+            in this bucket matching the arguments. The RPC call
+            returns a response when the iterator is consumed.
 
             As part of the response, you'll also get back an iterator.prefixes entity that lists object names
             up to and including the requested delimiter. Duplicate entries are omitted from this list.

samples/snippets/storage_list_files.py

@@ -29,6 +29,7 @@ def list_blobs(bucket_name):
     # Note: Client.list_blobs requires at least package version 1.17.0.
     blobs = storage_client.list_blobs(bucket_name)
 
+    # Note: The call returns a response only when the iterator is consumed.
     for blob in blobs:
         print(blob.name)
 

samples/snippets/storage_list_files_with_prefix.py

@@ -53,6 +53,7 @@ def list_blobs_with_prefix(bucket_name, prefix, delimiter=None):
     # Note: Client.list_blobs requires at least package version 1.17.0.
     blobs = storage_client.list_blobs(bucket_name, prefix=prefix, delimiter=delimiter)
 
+    # Note: The call returns a response only when the iterator is consumed.
     print("Blobs:")
     for blob in blobs:
         print(blob.name)