[Messaging] Client Lifetime Docs (Azure#30061)

The focus of these changes is to add the remarks for client lifetime to
the Service Bus clients and tune the verbiage for the Event Hubs versions.

Author: jsquire

sdk/eventhub/Azure.Messaging.EventHubs.Processor/src/EventProcessorClient.cs

@@ -32,9 +32,9 @@ namespace Azure.Messaging.EventHubs
     ///
     /// <remarks>
     ///   The <see cref="EventProcessorClient" /> is safe to cache and use for the lifetime of an application, and that is best practice when the application
-    ///   processes events regularly or semi-regularly.  The processor holds responsibility for efficient resource management, working to keep resource usage low during
-    ///   periods of inactivity and manage health during periods of higher use.  Calling either the <see cref="StopProcessingAsync" /> or <see cref="StopProcessing" />
-    ///   method when processing is complete or as the application is shutting down will ensure that network resources and other unmanaged objects are properly cleaned up.
+    ///   processes events regularly or semi-regularly.  The processor is responsible for ensuring efficient network, CPU, and memory use.  Calling either
+    ///   <see cref="StopProcessingAsync" /> or <see cref="StopProcessing" /> when processing is complete or as the application is shutting down will ensure
+    ///   that network resources and other unmanaged objects are properly cleaned up.
     /// </remarks>
     ///
     [SuppressMessage("Usage", "CA1001:Types that own disposable fields should be disposable.", Justification = "Disposal is managed internally as part of the Stop operation.")]

sdk/eventhub/Azure.Messaging.EventHubs/src/Consumer/EventHubConsumerClient.cs

@@ -33,11 +33,12 @@ namespace Azure.Messaging.EventHubs.Consumer
     /// </summary>
     ///
     /// <remarks>
-    ///   The <see cref="EventHubConsumerClient" /> is safe to cache and use for the lifetime of an application, and that is best practice when the application
-    ///   reads events regularly or semi-regularly.  The consumer holds responsibility for efficient resource management, working to keep resource usage low during
-    ///   periods of inactivity and manage health during periods of higher use.  Calling either the <see cref="CloseAsync" /> or <see cref="DisposeAsync" />
-    ///   method as the application is shutting down will ensure that network resources and other unmanaged objects are properly cleaned up.
+    ///   The <see cref="EventHubConsumerClient" /> is safe to cache and use for the lifetime of an application, which is the best practice when the application
+    ///   reads events regularly or semi-regularly.  The consumer is responsible for ensuring efficient network, CPU, and memory use.  Calling either
+    ///   <see cref="CloseAsync" /> or <see cref="DisposeAsync" /> as the application is shutting down will ensure that network resources and other
+    ///   unmanaged objects are properly cleaned up.
     /// </remarks>
+    ///
     [SuppressMessage("Usage", "AZC0007:DO provide a minimal constructor that takes only the parameters required to connect to the service.", Justification = "Event Hubs are AMQP-based services and don't use ClientOptions functionality")]
     public class EventHubConsumerClient : IAsyncDisposable
     {

sdk/eventhub/Azure.Messaging.EventHubs/src/Primitives/EventProcessor.cs

@@ -31,10 +31,9 @@ namespace Azure.Messaging.EventHubs.Primitives
     /// <typeparam name="TPartition">The context of the partition for which an operation is being performed.</typeparam>
     ///
     /// <remarks>
-    ///   The <see cref="EventProcessor{TPartition}" /> is safe to cache and use for the lifetime of an application, and that is best practice when the application
-    ///   processes events regularly or semi-regularly.  The processor holds responsibility for efficient resource management, working to keep resource usage low during
-    ///   periods of inactivity and manage health during periods of higher use.  Calling either the <see cref="StopProcessingAsync" /> or <see cref="StopProcessing" />
-    ///   method when processing is complete or as the application is shutting down will ensure that network resources and other unmanaged objects are properly cleaned up.
+    ///   The <see cref="EventProcessor{TPartition}" /> is safe to cache and use for the lifetime of an application, which is the recommended approach.
+    ///   The processor is responsible for ensuring efficient network, CPU, and memory use.  Calling either <see cref="StopProcessingAsync" /> or <see cref="StopProcessing" />
+    ///   when all processing is complete or as the application is shutting down will ensure that network resources and other unmanaged objects are properly cleaned up.
     /// </remarks>
     ///
     [SuppressMessage("Microsoft.Design", "CA1001:TypesThatOwnDisposableFieldsShouldBeDisposable")]

sdk/eventhub/Azure.Messaging.EventHubs/src/Primitives/PartitionReceiver.cs

@@ -25,10 +25,10 @@ namespace Azure.Messaging.EventHubs.Primitives
     ///   be used for reading and processing events for the majority of scenarios.  The partition receiver is
     ///   intended to enable scenarios with special needs which require more direct control.</para>
     ///
-    ///   <para>The <see cref="PartitionReceiver" /> is safe to cache and use for the lifetime of an application, and that is best practice when the application
-    ///   reads events regularly or semi-regularly.  The receiver holds responsibility for efficient resource management, working to keep resource usage low during
-    ///   periods of inactivity and manage health during periods of higher use.  Calling either the <see cref="CloseAsync" /> or <see cref="DisposeAsync" />
-    ///   method as the application is shutting down will ensure that network resources and other unmanaged objects are properly cleaned up.</para>
+    ///   <para>The <see cref="PartitionReceiver" /> is safe to cache and use for the lifetime of an application, and which is the best practice when the application
+    ///   reads events regularly or semi-regularly.  The receiver is responsible for ensuring efficient network, CPU, and memory use.  Calling either
+    ///   <see cref="CloseAsync" /> or <see cref="DisposeAsync" /> as the application is shutting down will ensure that network resources and other unmanaged
+    ///   objects are properly cleaned up.</para>
     /// </remarks>
     ///
     /// <seealso href="https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor">Azure.Messaging.EventHubs.Processor (NuGet)</seealso>

sdk/eventhub/Azure.Messaging.EventHubs/src/Producer/EventHubBufferedProducerClient.cs

@@ -46,9 +46,10 @@ namespace Azure.Messaging.EventHubs.Producer
     ///
     /// <remarks>
     ///   The <see cref="EventHubBufferedProducerClient"/> is safe to cache and use as a singleton for the lifetime of an
-    ///   application. This is the recommended approach, since the client is responsible for efficient network,
-    ///   CPU, and memory use. Calling <see cref="CloseAsync(bool, CancellationToken)"/> or <see cref="DisposeAsync"/>
-    ///   is required so that resources can be cleaned up after use.
+    ///   application, which is the recommended approach.  The producer is responsible for ensuring efficient network,
+    ///   CPU, and memory use. Calling either <see cref="CloseAsync(bool, CancellationToken)"/> or <see cref="DisposeAsync"/>
+    ///   when no more events will be enqueued or as the application is shutting down is required so that the buffer can be flushed
+    ///   and resources cleaned up properly.
     /// </remarks>
     ///
     /// <seealso cref="EventHubProducerClient" />

sdk/eventhub/Azure.Messaging.EventHubs/src/Producer/EventHubProducerClient.cs

@@ -48,10 +48,9 @@ namespace Azure.Messaging.EventHubs.Producer
     ///   </list>
     ///
     ///   <para>
-    ///     The <see cref="EventHubProducerClient" /> is safe to cache and use for the lifetime of an application, and that is best practice when the application
-    ///     publishes events regularly or semi-regularly.  The producer holds responsibility for efficient resource management, working to keep resource usage low during
-    ///     periods of inactivity and manage health during periods of higher use.  Calling either the <see cref="CloseAsync" /> or <see cref="DisposeAsync" />
-    ///     method as the application is shutting down will ensure that network resources and other unmanaged objects are properly cleaned up.
+    ///     The <see cref="EventHubProducerClient" /> is safe to cache and use for the lifetime of an application, which is the best practice when the application
+    ///     publishes events regularly or semi-regularly.  The producer is responsible for ensuring efficient network, CPU, and memory use.  Calling either
+    ///     <see cref="CloseAsync" /> or <see cref="DisposeAsync" /> as the application is shutting down will ensure that network resources and other unmanaged objects are properly cleaned up.
     ///   </para>
     /// </remarks>
     ///

sdk/servicebus/Azure.Messaging.ServiceBus/src/Client/ServiceBusClient.cs

@@ -17,6 +17,13 @@ namespace Azure.Messaging.ServiceBus
     /// same AMQP connection. Disposing the <see cref="ServiceBusClient"/> will cause the AMQP
     /// connection to close.
     /// </summary>
+    /// <remarks>
+    /// The <see cref="ServiceBusClient" /> is safe to cache and use for the lifetime of an
+    /// application, which is the best practice when the application is making use of Service Bus
+    /// regularly or semi-regularly.  The client is responsible for ensuring efficient network, CPU,
+    /// and memory use.  Calling <see cref="DisposeAsync" /> as the application is shutting down
+    /// will ensure that network resources and other unmanaged objects are properly cleaned up.
+    ///</remarks>
     public class ServiceBusClient : IAsyncDisposable
     {
         private readonly ServiceBusClientOptions _options;

sdk/servicebus/Azure.Messaging.ServiceBus/src/Processor/ServiceBusProcessor.cs

@@ -23,6 +23,14 @@ namespace Azure.Messaging.ServiceBus
     /// property. The error handler is specified with the <see cref="ProcessErrorAsync"/> property.
     /// To start processing after the handlers have been specified, call <see cref="StartProcessingAsync"/>.
     /// </summary>
+    /// <remarks>
+    /// The <see cref="ServiceBusProcessor" /> is safe to cache and use for the lifetime of an application
+    /// or until the <see cref="ServiceBusClient" /> that it was created by is disposed. Caching the processor
+    /// is recommended when the application is processing messages regularly.  The sender is responsible for
+    /// ensuring efficient network, CPU, and memory use. Calling <see cref="DisposeAsync" /> on the
+    /// associated <see cref="ServiceBusClient" /> as the application is shutting down will ensure that
+    /// network resources and other unmanaged objects used by the processor are properly cleaned up.
+    /// </remarks>
 #pragma warning disable CA1001 // Types that own disposable fields should be disposable
     public class ServiceBusProcessor : IAsyncDisposable
 #pragma warning restore CA1001 // Types that own disposable fields should be disposable
@@ -1117,4 +1125,4 @@ private async Task ReconcileConcurrencyAsync()
             _currentConcurrentSessions = maxConcurrentSessions;
         }
     }
-}
+}

sdk/servicebus/Azure.Messaging.ServiceBus/src/Processor/ServiceBusSessionProcessor.cs

@@ -18,6 +18,14 @@ namespace Azure.Messaging.ServiceBus
     /// property. The error handler is specified with the <see cref="ProcessErrorAsync"/> property.
     /// To start processing after the handlers have been specified, call <see cref="StartProcessingAsync"/>.
     /// </summary>
+    /// <remarks>
+    /// The <see cref="ServiceBusSessionProcessor" /> is safe to cache and use for the lifetime of an application
+    /// or until the <see cref="ServiceBusClient" /> that it was created by is disposed. Caching the processor
+    /// is recommended when the application is processing messages regularly.  The sender is responsible for
+    /// ensuring efficient network, CPU, and memory use. Calling <see cref="DisposeAsync" /> on the
+    /// associated <see cref="ServiceBusClient" /> as the application is shutting down will ensure that
+    /// network resources and other unmanaged objects used by the processor are properly cleaned up.
+    /// </remarks>
     public class ServiceBusSessionProcessor : IAsyncDisposable
     {
         /// <summary>
@@ -331,4 +339,4 @@ public void UpdateConcurrency(int maxConcurrentSessions, int maxConcurrentCallsP
             InnerProcessor.UpdateConcurrency(maxConcurrentSessions, maxConcurrentCallsPerSession);
         }
     }
-}
+}

sdk/servicebus/Azure.Messaging.ServiceBus/src/Receiver/ServiceBusReceiver.cs

@@ -22,6 +22,15 @@ namespace Azure.Messaging.ServiceBus
     /// <see cref="ServiceBusReceivedMessage" /> and settling messages from Queues and Subscriptions.
     /// It is constructed by calling <see cref="ServiceBusClient.CreateReceiver(string, ServiceBusReceiverOptions)"/>.
     /// </summary>
+    /// <remarks>
+    /// The <see cref="ServiceBusReceiver" /> is safe to cache and use for the lifetime of an
+    /// application or until the <see cref="ServiceBusClient" /> that it was created by is disposed.
+    /// Caching the receiver is recommended when the application is consuming messages
+    /// regularly or semi-regularly.  The receiver is responsible for ensuring efficient network, CPU,
+    /// and memory use.  Calling <see cref="DisposeAsync" /> on the associated <see cref="ServiceBusClient" />
+    /// as the application is shutting down will ensure that network resources and other unmanaged objects used
+    /// by the receiver are properly cleaned up.
+    ///</remarks>
     public class ServiceBusReceiver : IAsyncDisposable
     {
         /// <summary>
@@ -1197,4 +1206,4 @@ public virtual async ValueTask DisposeAsync()
         [EditorBrowsable(EditorBrowsableState.Never)]
         public override string ToString() => base.ToString();
     }
-}
+}