Added more docstring context and sample code for receive_messages()

sdk/storage/azure-storage-queue/azure/storage/queue/_queue_client.py

@@ -500,6 +500,17 @@ def receive_messages(self, **kwargs):
             messages to retrieve from the queue, up to a maximum of 32. If
             fewer are visible, the visible messages are returned. By default,
             a single message is retrieved from the queue with this operation.
+            When retrieving these pages it is important to pass the output to `by_page()`.
+            These pages and their content can be iterated through using `next()`.
+            .. admonition:: Example:
+
+                .. literalinclude:: ../samples/queue_samples_message.py
+                    :start-after: [START receive_messages_listing]
+                    :end-before: [END receive_messages_listing]
+                    :language: python
+                    :dedent: 12
+                    :caption: List pages and corresponding messages from the queue.
+
         :keyword int visibility_timeout:
             If not specified, the default value is 0. Specifies the
             new visibility timeout value, in seconds, relative to server time.

sdk/storage/azure-storage-queue/azure/storage/queue/aio/_queue_client_async.py

@@ -419,6 +419,7 @@ def receive_messages(self, **kwargs):
             messages to retrieve from the queue, up to a maximum of 32. If
             fewer are visible, the visible messages are returned. By default,
             a single message is retrieved from the queue with this operation.
+            When retrieving these pages it is important to pass the output to `by_page()`.
         :keyword int visibility_timeout:
             If not specified, the default value is 0. Specifies the
             new visibility timeout value, in seconds, relative to server time.

sdk/storage/azure-storage-queue/samples/queue_samples_message.py

@@ -146,14 +146,45 @@ def send_and_receive_messages(self):
             # Delete the queue
             queue.delete_queue()
 
-    def delete_and_clear_messages(self):
+    def list_message_pages(self):
         # Instantiate a queue client
         from azure.storage.queue import QueueClient
         queue = QueueClient.from_connection_string(self.connection_string, "myqueue4")
 
         # Create the queue
         queue.create_queue()
 
+        try:
+            queue.send_message(u"message1")
+            queue.send_message(u"message2")
+            queue.send_message(u"message3")
+            queue.send_message(u"message4")
+            queue.send_message(u"message5")
+            queue.send_message(u"message6", visibility_timeout=30)
+
+            # [START receive_messages_listing]
+            # Store two messages in each page
+            messages = queue.receive_messages(messages_per_page=2).by_page()
+
+            # Iterate through the page lists
+            print(list(next(messages)))
+            print(list(next(messages)))
+
+            # Third list has one message since `message6` is still invisible
+            print(list(next(messages)))
+            # [END receive_messages_listing]
+
+        finally:
+            queue.delete_queue()
+
+    def delete_and_clear_messages(self):
+        # Instantiate a queue client
+        from azure.storage.queue import QueueClient
+        queue = QueueClient.from_connection_string(self.connection_string, "myqueue5")
+
+        # Create the queue
+        queue.create_queue()
+
         try:
             # Send messages
             queue.send_message(u"message1")
@@ -181,7 +212,7 @@ def delete_and_clear_messages(self):
     def peek_messages(self):
         # Instantiate a queue client
         from azure.storage.queue import QueueClient
-        queue = QueueClient.from_connection_string(self.connection_string, "myqueue5")
+        queue = QueueClient.from_connection_string(self.connection_string, "myqueue6")
 
         # Create the queue
         queue.create_queue()
@@ -213,7 +244,7 @@ def peek_messages(self):
     def update_message(self):
         # Instantiate a queue client
         from azure.storage.queue import QueueClient
-        queue = QueueClient.from_connection_string(self.connection_string, "myqueue6")
+        queue = QueueClient.from_connection_string(self.connection_string, "myqueue7")
 
         # Create the queue
         queue.create_queue()
@@ -245,6 +276,7 @@ def update_message(self):
     sample.set_access_policy()
     sample.queue_metadata()
     sample.send_and_receive_messages()
+    sample.list_message_pages()
     sample.delete_and_clear_messages()
     sample.peek_messages()
     sample.update_message()