ServiceBus Track2 Small doc and readme cleanup prior to preview 2 (Azure#11195)

* Add additional samples to readme per doc review comments.
* Make message settlement docstrings more precise

Author: KieranBrantnerMagee

sdk/servicebus/azure-servicebus/README.md

@@ -123,6 +123,7 @@ The following sections provide several code snippets covering some of the most c
 
 * [Send a message to a queue](#send-a-message-to-a-queue)
 * [Receive a message from a queue](#receive-a-message-from-a-queue)
+* [Sending and receiving a message from a session enabled subscription](#sending-and-receiving-a-message-from-a-session-enabled-subscription)
 * [Defer a message on receipt](#defer-a-message-on-receipt)
 
 To perform management tasks such as creating and deleting queues/topics/subscriptions, please utilize the azure-mgmt-servicebus library, available [here][servicebus_management_repository].
@@ -165,6 +166,30 @@ with ServiceBusClient.from_connection_string(connstr) as client:
             msg.complete()
 ```
 
+### Sending and receiving a message from a session enabled subscription
+
+Sessions provide first-in-first-out and single-receiver semantics on top of a queue or subscription.  While the actual receive syntax is the same, initialization differs slightly.
+
+```Python
+from azure.servicebus import ServiceBusClient, Message
+
+import os
+connstr = os.environ['SERVICE_BUS_CONN_STR']
+topic_name = os.environ['SERVICE_BUS_TOPIC_NAME']
+subscription_name = os.environ['SERVICE_BUS_SUBSCRIPTION_NAME']
+session_id = os.environ.get('SERVICE_BUS_SESSION_ID')
+
+with ServiceBusClient.from_connection_string(connstr) as client:
+    with client.get_topic_sender(topic_name) as sender:
+        sender.send(Message("Session Enabled Message", session_id=session_id))
+
+    # If session_id is null here, will receive from the first available session.
+    with client.get_subscription_session_receiver(topic_name, subscription_name, session_id) as receiver:
+        for msg in receiver:
+            print(str(msg))
+            msg.complete()
+```
+
 ### Defer a message on receipt
 
 When receiving from a queue, you have multiple actions you can take on the messages you receive.  Where the prior example completes a message,

sdk/servicebus/azure-servicebus/azure/servicebus/_common/message.py

@@ -644,7 +644,7 @@ def abandon(self):
         # type: () -> None
         """Abandon the message.
 
-        This message will be returned to the queue to be reprocessed.
+        This message will be returned to the queue and made available to be received again.
 
         :rtype: None
         :raises: ~azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
@@ -661,8 +661,8 @@ def defer(self):
         # type: () -> None
         """Defer the message.
 
-        This message will remain in the queue but must be received
-        specifically by its sequence number in order to be processed.
+        This message will remain in the queue but must be requested
+        specifically by its sequence number in order to be received.
 
         :rtype: None
         :raises: ~azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.

sdk/servicebus/azure-servicebus/azure/servicebus/aio/_async_message.py

@@ -94,7 +94,9 @@ async def dead_letter(self, reason=None, description=None):
 
     async def abandon(self):
         # type: () -> None
-        """Abandon the message. This message will be returned to the queue to be reprocessed.
+        """Abandon the message. 
+        
+        This message will be returned to the queue and made available to be received again.
 
         :rtype: None
         :raises: ~azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
@@ -108,7 +110,10 @@ async def abandon(self):
 
     async def defer(self):
         # type: () -> None
-        """Abandon the message. This message will be returned to the queue to be reprocessed.
+        """Defers the message.
+        
+        This message will remain in the queue but must be requested
+        specifically by its sequence number in order to be received.
 
         :rtype: None
         :raises: ~azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.

sdk/servicebus/azure-servicebus/samples/async_samples/session_pool_receive_async.py

@@ -29,7 +29,7 @@ async def message_processing(servicebus_client, queue_name):
                     print("Message: {}".format(message))
                     print("Time to live: {}".format(message.header.time_to_live))
                     print("Sequence number: {}".format(message.sequence_number))
-                    print("Enqueue Sequence numger: {}".format(message.enqueue_sequence_number))
+                    print("Enqueue Sequence number: {}".format(message.enqueue_sequence_number))
                     print("Partition ID: {}".format(message.partition_id))
                     print("Partition Key: {}".format(message.partition_key))
                     print("Locked until: {}".format(message.locked_until_utc))

sdk/servicebus/azure-servicebus/samples/sync_samples/session_pool_receive.py

@@ -28,7 +28,7 @@ def message_processing(sb_client, queue_name, messages):
                     print("Message: {}".format(message))
                     print("Time to live: {}".format(message.header.time_to_live))
                     print("Sequence number: {}".format(message.sequence_number))
-                    print("Enqueue Sequence numger: {}".format(message.enqueue_sequence_number))
+                    print("Enqueue Sequence number: {}".format(message.enqueue_sequence_number))
                     print("Partition ID: {}".format(message.partition_id))
                     print("Partition Key: {}".format(message.partition_key))
                     print("Locked until: {}".format(message.locked_until_utc))