From 08a8b3b8181e806dedc7413f5991359f8a693655 Mon Sep 17 00:00:00 2001
From: Dan Lumpp <20948500+dlumpp@users.noreply.github.com>
Date: Thu, 12 Aug 2021 01:02:47 -0400
Subject: [PATCH] change XML docs on ServiceBusReceiver.ReceiveDeferred methods
 (#23283)

to correctly reflect MessageNotFound exception result
---
 .../Azure.Messaging.ServiceBus/src/Amqp/AmqpReceiver.cs   | 2 +-
 .../src/Core/TransportReceiver.cs                         | 2 +-
 .../src/Receiver/ServiceBusReceiver.cs                    | 8 ++++++--
 3 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/sdk/servicebus/Azure.Messaging.ServiceBus/src/Amqp/AmqpReceiver.cs b/sdk/servicebus/Azure.Messaging.ServiceBus/src/Amqp/AmqpReceiver.cs
index fdbaf909365f..8f3e7ca909bc 100644
--- a/sdk/servicebus/Azure.Messaging.ServiceBus/src/Amqp/AmqpReceiver.cs
+++ b/sdk/servicebus/Azure.Messaging.ServiceBus/src/Amqp/AmqpReceiver.cs
@@ -1258,7 +1258,7 @@ internal async Task SetStateInternal(
         /// </summary>
         /// <param name="sequenceNumbers">A <see cref="IList{SequenceNumber}"/> containing the sequence numbers to receive.</param>
         /// <param name="cancellationToken"></param>
-        /// <returns>Messages identified by sequence number are returned. Returns null if no messages are found.
+        /// <returns>Messages identified by sequence number are returned.
         /// Throws if the messages have not been deferred.</returns>
         /// <seealso cref="DeferAsync"/>
         public override async Task<IReadOnlyList<ServiceBusReceivedMessage>> ReceiveDeferredMessagesAsync(
diff --git a/sdk/servicebus/Azure.Messaging.ServiceBus/src/Core/TransportReceiver.cs b/sdk/servicebus/Azure.Messaging.ServiceBus/src/Core/TransportReceiver.cs
index b9147246e5bf..e52fca4e6ca1 100644
--- a/sdk/servicebus/Azure.Messaging.ServiceBus/src/Core/TransportReceiver.cs
+++ b/sdk/servicebus/Azure.Messaging.ServiceBus/src/Core/TransportReceiver.cs
@@ -172,7 +172,7 @@ public abstract Task DeadLetterAsync(
         /// </summary>
         /// <param name="sequenceNumbers">A <see cref="IList{SequenceNumber}"/> containing the sequence numbers to receive.</param>
         /// <param name="cancellationToken"></param>
-        /// <returns>Messages identified by sequence number are returned. Returns null if no messages are found.
+        /// <returns>Messages identified by sequence number are returned.
         /// Throws if the messages have not been deferred.</returns>
         /// <seealso cref="DeferAsync"/>
         public abstract Task<IReadOnlyList<ServiceBusReceivedMessage>> ReceiveDeferredMessagesAsync(
diff --git a/sdk/servicebus/Azure.Messaging.ServiceBus/src/Receiver/ServiceBusReceiver.cs b/sdk/servicebus/Azure.Messaging.ServiceBus/src/Receiver/ServiceBusReceiver.cs
index c354e8b3ede7..799aed3a11cd 100644
--- a/sdk/servicebus/Azure.Messaging.ServiceBus/src/Receiver/ServiceBusReceiver.cs
+++ b/sdk/servicebus/Azure.Messaging.ServiceBus/src/Receiver/ServiceBusReceiver.cs
@@ -950,10 +950,14 @@ private static void ThrowIfLockTokenIsEmpty(Guid lockToken)
         /// the <see cref="ServiceBusReceivedMessage.SequenceNumber"/>.</param>
         /// <param name="cancellationToken">An optional <see cref="CancellationToken"/> instance to signal the request to cancel the operation.</param>
         ///
-        /// <returns>The deferred message identified by the specified sequence number. Returns null if no message is found.
+        /// <returns>The deferred message identified by the specified sequence number.
         /// Throws if the message has not been deferred.</returns>
         /// <seealso cref="DeferMessageAsync(ServiceBusReceivedMessage, IDictionary{string, object}, CancellationToken)"/>
         /// <seealso cref="DeferMessageAsync(Guid, IDictionary{string, object}, CancellationToken)"/>
+        /// <exception cref="ServiceBusException">
+        ///   The specified sequence number does not correspond to a message that has been deferred.
+        ///   The <see cref="ServiceBusException.Reason" /> will be set to <see cref="ServiceBusFailureReason.MessageNotFound"/> in this case.
+        /// </exception>
         public virtual async Task<ServiceBusReceivedMessage> ReceiveDeferredMessageAsync(
             long sequenceNumber,
             CancellationToken cancellationToken = default) =>
@@ -966,7 +970,7 @@ public virtual async Task<ServiceBusReceivedMessage> ReceiveDeferredMessageAsync
         /// <param name="cancellationToken">An optional <see cref="CancellationToken"/> instance to signal the request to cancel the operation.</param>
         /// <param name="sequenceNumbers">An <see cref="IEnumerable{T}"/> containing the sequence numbers to receive.</param>
         ///
-        /// <returns>Messages identified by sequence number are returned. Returns null if no messages are found.
+        /// <returns>Messages identified by sequence number are returned.
         /// Throws if the messages have not been deferred.</returns>
         /// <seealso cref="DeferMessageAsync(ServiceBusReceivedMessage, IDictionary{string, object}, CancellationToken)"/>
         /// <seealso cref="DeferMessageAsync(Guid, IDictionary{string, object}, CancellationToken)"/>