Update other service client doc comments.

iothub/service/src/DigitalTwin/DigitalTwinClient.cs

@@ -19,8 +19,10 @@ namespace Microsoft.Azure.Devices
 {
     /// <summary>
     /// The Digital Twins Service Client contains methods to retrieve and update digital twin information, and invoke commands on a digital twin device.
-    /// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>
     /// </summary>
+    /// <remarks>
+    /// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>
+    /// </remarks>
     public class DigitalTwinClient : IDisposable
     {
         private const string HttpsEndpointPrefix = "https";
@@ -29,16 +31,20 @@ public class DigitalTwinClient : IDisposable
 
         /// <summary>
         /// Creates an instance of <see cref="DigitalTwinClient"/>, provided for unit testing purposes only.
-        /// Use the CreateFromConnectionString or Create method to create an instance to use the client.
         /// </summary>
         public DigitalTwinClient()
         {
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="DigitalTwinClient"/> class.</summary>
+        /// Creates DigitalTwinClient from an IoT hub connection string.
+        /// </summary>
         /// <param name="connectionString">The IoT hub's connection string.</param>
-        /// <param name="handlers">The delegating handlers to add to the http client pipeline. You can add handlers for tracing, implementing a retry strategy, routing requests through a proxy, etc.</param>
+        /// <param name="handlers">
+        /// The delegating handlers to add to the http client pipeline.
+        /// You can add handlers for tracing, implementing a retry strategy, routing requests through a proxy, etc.
+        /// </param>
+        /// <returns>A DigitalTwinsClient instance.</returns>
         public static DigitalTwinClient CreateFromConnectionString(string connectionString, params DelegatingHandler[] handlers)
         {
             connectionString.ThrowIfNullOrWhiteSpace(nameof(connectionString));
@@ -49,15 +55,21 @@ public static DigitalTwinClient CreateFromConnectionString(string connectionStri
         }
 
         /// <summary>
-        /// Creates an instance of <see cref="DigitalTwinClient"/>.
+        /// Creates DigitalTwinClient, authenticating using an identity in Azure Active Directory (AAD).
         /// </summary>
-        /// <param name="hostName">IoT hub host name.</param>
-        /// <param name="credential">Azure Active Directory credentials to authenticate with IoT hub. See <see cref="TokenCredential"/></param>
-        /// <param name="handlers">The delegating handlers to add to the http client pipeline. You can add handlers for tracing, implementing a retry strategy, routing requests through a proxy, etc.</param>
-        /// <returns>An instance of <see cref="DigitalTwinClient"/>.</returns>
         /// <remarks>
-        /// For more information on configuring IoT hub with Azure Active Directory, see <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-dev-guide-azure-ad-rbac"/>
+        /// For more about information on the options of authenticating using a derived instance of <see cref="TokenCredential"/>, see
+        /// <see href="https://docs.microsoft.com/dotnet/api/overview/azure/identity-readme"/>.
+        /// For more information on configuring IoT hub with Azure Active Directory, see
+        /// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-dev-guide-azure-ad-rbac"/>
         /// </remarks>
+        /// <param name="hostName">IoT hub host name.</param>
+        /// <param name="credential">Azure Active Directory (AAD) credentials to authenticate with IoT hub. See <see cref="TokenCredential"/></param>
+        /// <param name="handlers">
+        /// The delegating handlers to add to the http client pipeline. You can add handlers for tracing,
+        /// implementing a retry strategy, routing requests through a proxy, etc.
+        /// </param>
+        /// <returns>A DigitalTwinsClient instance.</returns>
         public static DigitalTwinClient Create(
             string hostName,
             TokenCredential credential,
@@ -78,12 +90,17 @@ public static DigitalTwinClient Create(
         }
 
         /// <summary>
-        /// Creates an instance of <see cref="DigitalTwinClient"/>.
+        /// Creates DigitalTwinClient using a shared access signature provided and refreshed as necessary by the caller.
         /// </summary>
+        /// <remarks>
+        /// Users may wish to build their own shared access signature (SAS) tokens rather than give the shared key to the SDK and let it manage signing and renewal.
+        /// The <see cref="AzureSasCredential"/> object gives the SDK access to the SAS token, while the caller can update it as necessary using the
+        /// <see cref="AzureSasCredential.Update(string)"/> method.
+        /// </remarks>
         /// <param name="hostName">IoT hub host name.</param>
         /// <param name="credential">Credential that generates a SAS token to authenticate with IoT hub. See <see cref="AzureSasCredential"/>.</param>
         /// <param name="handlers">The delegating handlers to add to the http client pipeline. You can add handlers for tracing, implementing a retry strategy, routing requests through a proxy, etc.</param>
-        /// <returns>An instance of <see cref="DigitalTwinClient"/>.</returns>
+        /// <returns>A DigitalTwinsClient instance.</returns>
         public static DigitalTwinClient Create(
             string hostName,
             AzureSasCredential credential,

iothub/service/src/JobClient/JobClient.cs

@@ -23,6 +23,9 @@ namespace Microsoft.Azure.Devices
     /// <summary>
     /// Job management
     /// </summary>
+    /// <remarks>
+    /// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>.
+    /// </remarks>
     public class JobClient : IDisposable
     {
         private const string _jobsUriFormat = "/jobs/v2/{0}?{1}";
@@ -37,8 +40,7 @@ public class JobClient : IDisposable
         private IHttpClientHelper _httpClientHelper;
 
         /// <summary>
-        /// Creates an instance of <see cref="JobClient"/>, provided for unit testing purposes only.
-        /// Use the CreateFromConnectionString method to create an instance to use the client.
+        /// Creates JobClient, provided for unit testing purposes only.
         /// </summary>
         public JobClient()
         {
@@ -62,22 +64,21 @@ internal JobClient(IotHubConnectionProperties connectionProperties, HttpTranspor
         }
 
         /// <summary>
-        /// Creates a JobClient from the IoT Hub connection string.
-        /// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>
+        /// Creates JobClient from the IoT hub connection string.
         /// </summary>
-        /// <param name="connectionString"> The IoT Hub connection string.</param>
-        /// <returns> A JobClient instance. </returns>
+        /// <param name="connectionString">The IoT hub connection string.</param>
+        /// <returns>A JobClient instance.</returns>
         public static JobClient CreateFromConnectionString(string connectionString)
         {
             return CreateFromConnectionString(connectionString, new HttpTransportSettings());
         }
 
         /// <summary>
-        /// Creates a JobClient from the IoT Hub connection string and HTTP transport settings
+        /// Creates JobClient from the IoT hub connection string and HTTP transport settings.
         /// </summary>
-        /// <param name="connectionString"> The IoT Hub connection string.</param>
-        /// <param name="transportSettings"> The HTTP transport settings.</param>
-        /// <returns> A JobClient instance. </returns>
+        /// <param name="connectionString">The IoT hub connection string.</param>
+        /// <param name="transportSettings">The HTTP transport settings.</param>
+        /// <returns>A JobClient instance.</returns>
         public static JobClient CreateFromConnectionString(string connectionString, HttpTransportSettings transportSettings)
         {
             if (transportSettings == null)
@@ -93,15 +94,18 @@ public static JobClient CreateFromConnectionString(string connectionString, Http
 #if !NET451
 
         /// <summary>
-        /// Creates an instance of <see cref="JobClient"/>.
+        /// Creates JobClient, authenticating using an identity in Azure Active Directory (AAD).
         /// </summary>
-        /// <param name="hostName">IoT hub host name.</param>
-        /// <param name="credential">Azure Active Directory credentials to authenticate with IoT hub. See <see cref="TokenCredential"/></param>
-        /// <param name="transportSettings">The HTTP transport settings.</param>
-        /// <returns>An instance of <see cref="JobClient"/>.</returns>
         /// <remarks>
-        /// For more information on configuring IoT hub with Azure Active Directory, see <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-dev-guide-azure-ad-rbac"/>
+        /// For more about information on the options of authenticating using a derived instance of <see cref="TokenCredential"/>, see
+        /// <see href="https://docs.microsoft.com/dotnet/api/overview/azure/identity-readme"/>.
+        /// For more information on configuring IoT hub with Azure Active Directory, see
+        /// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-dev-guide-azure-ad-rbac"/>
         /// </remarks>
+        /// <param name="hostName">IoT hub host name.</param>
+        /// <param name="credential">Azure Active Directory (AAD) credentials to authenticate with IoT hub. See <see cref="TokenCredential"/></param>
+        /// <param name="transportSettings">The HTTP transport settings.</param>
+        /// <returns>A JobClient instance.</returns>
         public static JobClient Create(
             string hostName,
             TokenCredential credential,
@@ -122,12 +126,17 @@ public static JobClient Create(
         }
 
         /// <summary>
-        /// Creates an instance of <see cref="JobClient"/>.
+        /// Creates JobClient using a shared access signature provided and refreshed as necessary by the caller.
         /// </summary>
+        /// <remarks>
+        /// Users may wish to build their own shared access signature (SAS) tokens rather than give the shared key to the SDK and let it manage signing and renewal.
+        /// The <see cref="AzureSasCredential"/> object gives the SDK access to the SAS token, while the caller can update it as necessary using the
+        /// <see cref="AzureSasCredential.Update(string)"/> method.
+        /// </remarks>
         /// <param name="hostName">IoT hub host name.</param>
         /// <param name="credential">Credential that generates a SAS token to authenticate with IoT hub. See <see cref="AzureSasCredential"/>.</param>
         /// <param name="transportSettings">The HTTP transport settings.</param>
-        /// <returns>An instance of <see cref="JobClient"/>.</returns>
+        /// <returns>A JobClient instance.</returns>
         public static JobClient Create(
             string hostName,
             AzureSasCredential credential,

iothub/service/src/RegistryManager.cs

@@ -14,6 +14,7 @@
 using Microsoft.Azure.Devices.Common.Exceptions;
 using Microsoft.Azure.Devices.Shared;
 using Newtonsoft.Json;
+using System.Diagnostics.CodeAnalysis;
 
 #if !NET451
 
@@ -26,9 +27,11 @@ namespace Microsoft.Azure.Devices
 {
     /// <summary>
     /// Contains methods that services can use to perform create, remove, update and delete operations on devices.
-    /// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>
     /// </summary>
-    [System.Diagnostics.CodeAnalysis.SuppressMessage(
+    /// <remarks>
+    /// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>
+    /// </remarks>
+    [SuppressMessage(
         "Naming",
         "CA1716:Identifiers should not match keywords",
         Justification = "Cannot change parameter names as it is considered a breaking change.")]
@@ -71,7 +74,6 @@ public class RegistryManager : IDisposable
 
         /// <summary>
         /// Creates an instance of RegistryManager, provided for unit testing purposes only.
-        /// Use the CreateFromConnectionString method to create an instance to use the client.
         /// </summary>
         public RegistryManager()
         {
@@ -97,9 +99,9 @@ internal RegistryManager(string iotHubName, IHttpClientHelper httpClientHelper)
         }
 
         /// <summary>
-        /// Creates a RegistryManager from the IoT Hub connection string.
+        /// Creates RegistryManager from an IoT hub connection string.
         /// </summary>
-        /// <param name="connectionString">The IoT Hub connection string.</param>
+        /// <param name="connectionString">The IoT hub connection string.</param>
         /// <returns>A RegistryManager instance.</returns>
         public static RegistryManager CreateFromConnectionString(string connectionString)
         {
@@ -128,7 +130,7 @@ public static RegistryManager CreateFromConnectionString(string connectionString
 #if !NET451
 
         /// <summary>
-        /// Creates an instance of RegistryManager, authenticating using an identity in Azure Active Directory (AAD).
+        /// Creates RegistryManager, authenticating using an identity in Azure Active Directory (AAD).
         /// </summary>
         /// <remarks>
         /// For more about information on the options of authenticating using a derived instance of <see cref="TokenCredential"/>, see
@@ -160,7 +162,7 @@ public static RegistryManager Create(
         }
 
         /// <summary>
-        /// Creates an instance of RegistryManager using a shared access signature provided and refreshed as necessary by the caller.
+        /// Creates RegistryManager using a shared access signature provided and refreshed as necessary by the caller.
         /// </summary>
         /// <remarks>
         /// Users may wish to build their own shared access signature (SAS) tokens rather than give the shared key to the SDK and let it manage signing and renewal.

iothub/service/src/ServiceClient.cs

@@ -45,8 +45,10 @@ public enum TransportType
 
     /// <summary>
     /// Contains methods that services can use to send messages to devices
-    /// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>
     /// </summary>
+    /// <remarks>
+    /// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>
+    /// </remarks>
     public class ServiceClient : IDisposable
     {
         private const string StatisticsUriFormat = "/statistics/service?" + ClientApiVersionHelper.ApiVersionQueryString;
@@ -116,11 +118,11 @@ internal ServiceClient(IotHubConnection connection, IHttpClientHelper httpClient
         }
 
         /// <summary>
-        /// Create an instance of ServiceClient from the specified IoT Hub connection string.
+        /// Creates ServiceClient from an IoT hub connection string.
         /// </summary>
-        /// <param name="connectionString">Connection string for the IoT Hub.</param>
+        /// <param name="connectionString">Connection string for the IoT hub.</param>
         /// <param name="options">The <see cref="ServiceClientOptions"/> that allow configuration of the service client instance during initialization.</param>
-        /// <returns>An instance of ServiceClient.</returns>
+        /// <returns>A ServiceClient instance.</returns>
         public static ServiceClient CreateFromConnectionString(string connectionString, ServiceClientOptions options = default)
         {
             return CreateFromConnectionString(connectionString, TransportType.Amqp, options);
@@ -129,17 +131,20 @@ public static ServiceClient CreateFromConnectionString(string connectionString,
 #if !NET451
 
         /// <summary>
-        /// Creates a <see cref="ServiceClient"/> using Azure Active Directory credentials and the specified transport type.
+        /// Creates ServiceClient, authenticating using an identity in Azure Active Directory (AAD).
         /// </summary>
+        /// <remarks>
+        /// For more about information on the options of authenticating using a derived instance of <see cref="TokenCredential"/>, see
+        /// <see href="https://docs.microsoft.com/dotnet/api/overview/azure/identity-readme"/>.
+        /// For more information on configuring IoT hub with Azure Active Directory, see
+        /// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-dev-guide-azure-ad-rbac"/>
+        /// </remarks>
         /// <param name="hostName">IoT hub host name.</param>
         /// <param name="credential">Azure Active Directory credentials to authenticate with IoT hub. See <see cref="TokenCredential"/></param>
         /// <param name="transportType">Specifies whether Amqp or Amqp_WebSocket_Only transport is used.</param>
         /// <param name="transportSettings">Specifies the AMQP_WS and HTTP proxy settings for service client.</param>
         /// <param name="options">The options that allow configuration of the service client instance during initialization.</param>
-        /// <returns>An instance of <see cref="ServiceClient"/>.</returns>
-        /// <remarks>
-        /// For more information on configuring IoT hub with Azure Active Directory, see <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-dev-guide-azure-ad-rbac"/>
-        /// </remarks>
+        /// <returns>A ServiceClient instance.</returns>
         public static ServiceClient Create(
             string hostName,
             TokenCredential credential,
@@ -168,14 +173,19 @@ public static ServiceClient Create(
         }
 
         /// <summary>
-        /// Creates a <see cref="ServiceClient"/> using SAS token and the specified transport type.
+        /// Creates ServiceClient using a shared access signature provided and refreshed as necessary by the caller.
         /// </summary>
+        /// <remarks>
+        /// Users may wish to build their own shared access signature (SAS) tokens rather than give the shared key to the SDK and let it manage signing and renewal.
+        /// The <see cref="AzureSasCredential"/> object gives the SDK access to the SAS token, while the caller can update it as necessary using the
+        /// <see cref="AzureSasCredential.Update(string)"/> method.
+        /// </remarks>
         /// <param name="hostName">IoT hub host name.</param>
         /// <param name="credential">Credential that generates a SAS token to authenticate with IoT hub. See <see cref="AzureSasCredential"/>.</param>
         /// <param name="transportType">Specifies whether Amqp or Amqp_WebSocket_Only transport is used.</param>
         /// <param name="transportSettings">Specifies the AMQP_WS and HTTP proxy settings for service client.</param>
         /// <param name="options">The options that allow configuration of the service client instance during initialization.</param>
-        /// <returns>An instance of <see cref="ServiceClient"/>.</returns>
+        /// <returns>A ServiceClient instance.</returns>
         public static ServiceClient Create(
             string hostName,
             AzureSasCredential credential,