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.
+            `by_page()` can be used to provide a page iterator on the AsyncItemPaged if messages_per_page is set.
+            `next()` can be used to get the next page.
+        .. 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,8 @@ 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.
+            `by_page()` can be used to provide a page iterator on the AsyncItemPaged if messages_per_page is set.
+            `next()` can be used to get the next 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,47 @@ 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")
+
+            # [START receive_messages_listing]
+            # Store two messages in each page
+            message_batches = queue.receive_messages(messages_per_page=2).by_page()
+
+            # Iterate through the page lists
+            print(list(next(message_batches)))
+            print(list(next(message_batches)))
+
+            # There are two iterations in the last page as well.
+            last_page = next(message_batches)
+            for message in last_page:
+                print(message)
+            # [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 +214,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 +246,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 +278,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()