fix(iot-service): Add xml comments to public types and methods (#1759)

common/src/device/provisioning/transport/RegistrationOperationStatus.cs

@@ -30,7 +30,7 @@ public RegistrationOperationStatus()
         /// Initializes a new instance of the RegistrationOperationStatus
         /// class.
         /// </summary>
-        /// <param name="operationId">Operation ID.</param>
+        /// <param name="operationId">Operation Id.</param>
         /// <param name="status">Device enrollment status. Possible values
         /// include: 'unassigned', 'assigning', 'assigned', 'failed',
         /// 'disabled'</param>
@@ -53,7 +53,7 @@ public RegistrationOperationStatus(
         partial void CustomInit();
 
         /// <summary>
-        /// Gets or sets operation ID.
+        /// Gets or sets operation Id.
         /// </summary>
         [JsonProperty(PropertyName = "operationId")]
         public string OperationId { get; set; }

iothub/device/src/Common/UrlEncodedDictionarySerializer.cs

@@ -125,7 +125,7 @@ public static string Serialize(IEnumerable<KeyValuePair<string, string>> propert
                 propertiesCount++;
             }
 
-            //Optimization for most common case: only correlation ID is present
+            //Optimization for most common case: only correlation Id is present
             if (propertiesCount == 1 && firstProperty.HasValue)
             {
                 return firstProperty.Value.Value == null ?

iothub/device/src/Common/WebApi/CustomHeaderConstants.cs

@@ -3,7 +3,7 @@
 
 namespace Microsoft.Azure.Devices.Client
 {
-    static class CustomHeaderConstants
+    internal static class CustomHeaderConstants
     {
         /// <summary>
         /// Used in message responses and feedback
@@ -132,19 +132,19 @@ static class CustomHeaderConstants
 
         /// <summary>
         /// x-ms-client-principal-name
-        /// Set to the principal ID / UPN of the client JWT making the request.
+        /// Set to the principal Id / UPN of the client JWT making the request.
         /// </summary>
         public const string PrincipalName = "x-ms-client-principal-name";
 
         /// <summary>
         /// x-ms-client-tenant-id
-        /// Set to the tenant ID of the client JWT making the request.
+        /// Set to the tenant Id of the client JWT making the request.
         /// </summary>
         public const string ClientTenantId = "x-ms-client-tenant-id";
 
         /// <summary>
         /// x-ms-client-audience
-        /// Set to the tenant ID of the client JWT making the request.
+        /// Set to the tenant Id of the client JWT making the request.
         /// </summary>
         public const string ClientAudience = "x-ms-client-audience";
 
@@ -168,7 +168,7 @@ static class CustomHeaderConstants
 
         /// <summary>
         /// x-ms-client-request-id
-        /// Caller-specified request ID, in the form of a GUID with no decoration such as curly braces
+        /// Caller-specified request Id, in the form of a GUID with no decoration such as curly braces
         /// (e.g. client-request-id: 9C4D50EE-2D56-4CD3-8152-34347DC9F2B0).
         /// A caller-defined value that identifies the given request.   If specified, this will be
         /// included in response information as a way to map the request.
@@ -210,7 +210,7 @@ static class CustomHeaderConstants
         public const string RequestId = "x-ms-request-id";
 
         /// <summary>
-        /// Used to supply module ID of invoking module when used by module to invoke method on other modules/devices.
+        /// Used to supply module Id of invoking module when used by module to invoke method on other modules/devices.
         /// </summary>
         public const string ModuleId = "x-ms-edge-moduleId";
 

iothub/device/src/DeviceClient.cs

@@ -28,7 +28,7 @@ private DeviceClient(InternalClient internalClient)
 
             if (InternalClient.IotHubConnectionString?.ModuleId != null)
             {
-                throw new ArgumentException("A module ID was specified in the connection string - please use ModuleClient for modules.");
+                throw new ArgumentException("A module Id was specified in the connection string - please use ModuleClient for modules.");
             }
 
             if (Logging.IsEnabled)

iothub/device/src/MethodRequestInternal.cs

@@ -48,7 +48,7 @@ internal MethodRequestInternal(string name, string requestId, Stream bodyStream,
         internal string Name { get; private set; }
 
         /// <summary>
-        /// the request ID for the transport layer
+        /// the request Id for the transport layer
         /// </summary>
         internal string RequestId { get; private set; }
 

iothub/device/src/ModuleClient.cs

@@ -40,7 +40,7 @@ internal ModuleClient(InternalClient internalClient, ICertificateValidator certV
 
             if (string.IsNullOrWhiteSpace(InternalClient.IotHubConnectionString?.ModuleId))
             {
-                throw new ArgumentException("A valid module ID should be specified to create a ModuleClient");
+                throw new ArgumentException("A valid module Id should be specified to create a ModuleClient");
             }
 
             if (Logging.IsEnabled)

iothub/device/src/Transport/Mqtt/MqttTransportHandler.cs

@@ -48,8 +48,8 @@ internal sealed class MqttTransportHandler : TransportHandler, IMqttIotHubEventH
 
         // Topic names for retrieving a device's twin properties.
         // The client first subscribes to "$iothub/twin/res/#", to receive the operation's responses.
-        // It then sends an empty message to the topic "$iothub/twin/GET/?$rid={request id}, with a populated value for request ID.
-        // The service then sends a response message containing the device twin data on topic "$iothub/twin/res/{status}/?$rid={request id}", using the same request ID as the request.
+        // It then sends an empty message to the topic "$iothub/twin/GET/?$rid={request id}, with a populated value for request Id.
+        // The service then sends a response message containing the device twin data on topic "$iothub/twin/res/{status}/?$rid={request id}", using the same request Id as the request.
 
         private const string TwinResponseTopicFilter = "$iothub/twin/res/#";
         private const string TwinResponseTopicPrefix = "$iothub/twin/res/";
@@ -58,8 +58,8 @@ internal sealed class MqttTransportHandler : TransportHandler, IMqttIotHubEventH
 
         // Topic name for updating device twin's reported properties.
         // The client first subscribes to "$iothub/twin/res/#", to receive the operation's responses.
-        // The client then sends a message containing the twin update to "$iothub/twin/PATCH/properties/reported/?$rid={request id}", with a populated value for request ID.
-        // The service then sends a response message containing the new ETag value for the reported properties collection on the topic "$iothub/twin/res/{status}/?$rid={request id}", using the same request ID as the request.
+        // The client then sends a message containing the twin update to "$iothub/twin/PATCH/properties/reported/?$rid={request id}", with a populated value for request Id.
+        // The service then sends a response message containing the new ETag value for the reported properties collection on the topic "$iothub/twin/res/{status}/?$rid={request id}", using the same request Id as the request.
         private const string TwinPatchTopic = "$iothub/twin/PATCH/properties/reported/?$rid={0}";
 
         // Topic names for receiving twin desired property update notifications.
@@ -70,7 +70,7 @@ internal sealed class MqttTransportHandler : TransportHandler, IMqttIotHubEventH
         // Topic name for responding to direct methods.
         // The client first subscribes to "$iothub/methods/POST/#".
         // The service sends method requests to the topic "$iothub/methods/POST/{method name}/?$rid={request id}".
-        // The client responds to the direct method invocation by sending a message to the topic "$iothub/methods/res/{status}/?$rid={request id}", using the same request ID as the request.
+        // The client responds to the direct method invocation by sending a message to the topic "$iothub/methods/res/{status}/?$rid={request id}", using the same request Id as the request.
 
         private const string MethodPostTopicFilter = "$iothub/methods/POST/#";
         private const string MethodPostTopicPrefix = "$iothub/methods/POST/";

iothub/service/src/Common/Exceptions/JobNotFoundException.cs

@@ -17,7 +17,7 @@ public sealed class JobNotFoundException : IotHubException
         /// </summary>
         /// <param name="jobId">The Id of the job whose details are unavailable on IoT Hub.</param>
         public JobNotFoundException(string jobId)
-            : base($"Job with ID '{jobId}' not found")
+            : base($"Job with Id '{jobId}' not found")
         {
         }
 

iothub/service/src/Common/Extensions/AmqpExtensions.cs

@@ -1,11 +1,11 @@
 // Copyright (c) Microsoft. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+using System.Threading.Tasks;
+using Microsoft.Azure.Amqp;
+
 namespace Microsoft.Azure.Devices.Common.Extensions
 {
-    using System.Threading.Tasks;
-    using Microsoft.Azure.Amqp;
-
     /// <summary>
     /// Contains extension methods for amqp
     /// </summary>
@@ -18,8 +18,7 @@ internal static class AmqpExtensions
         /// <returns></returns>
         internal static async Task<ReceivingAmqpLink> GetReceivingLinkAsync(this FaultTolerantAmqpObject<ReceivingAmqpLink> faultTolerantReceivingLink)
         {
-            ReceivingAmqpLink receivingLink;
-            if (!faultTolerantReceivingLink.TryGetOpenedObject(out receivingLink))
+            if (!faultTolerantReceivingLink.TryGetOpenedObject(out ReceivingAmqpLink receivingLink))
             {
                 receivingLink = await faultTolerantReceivingLink.GetOrCreateAsync(IotHubConnection.DefaultOpenTimeout).ConfigureAwait(false);
             }

iothub/service/src/Common/Extensions/CommonExtensions.cs

@@ -93,7 +93,7 @@ public static string EnsureStartsWith(this string value, char prefix)
         /// <summary>
         /// Gets the value of the specified key, if present
         /// </summary>
-        /// <param name="map">The dictionary containing the specifed key</param>
+        /// <param name="map">The dictionary containing the specified key</param>
         /// <param name="keyName">The key of the desired value</param>
         /// <returns>The value, if present</returns>
         public static string GetValueOrDefault(this IDictionary<string, string> map, string keyName)
@@ -165,12 +165,10 @@ public static string GetIotHubNameFromHostName(this HttpRequestMessage requestMe
             // {IotHubname}.[env-specific-sub-domain.]IotHub[-int].net
 
             string[] hostNameParts = requestMessage.RequestUri.Host.Split('.');
-            if (hostNameParts.Length < 3)
-            {
-                throw new ArgumentException("Invalid request URI");
-            }
 
-            return hostNameParts[0];
+            return hostNameParts.Length < 3
+                ? throw new ArgumentException("Invalid request URI")
+                : hostNameParts[0];
         }
 
         /// <summary>
@@ -180,30 +178,29 @@ public static string GetIotHubNameFromHostName(this HttpRequestMessage requestMe
         /// <returns>The hub name</returns>
         public static string GetIotHubName(this HttpRequestMessage requestMessage)
         {
-            if (!TryGetIotHubName(requestMessage, out string iotHubName))
-            {
-                throw new ArgumentException("Invalid request URI");
-            }
-
-            return iotHubName;
+            return !TryGetIotHubName(requestMessage, out string iotHubName)
+                ? throw new ArgumentException("Invalid request URI")
+                : iotHubName;
         }
 
 #if NET451
+        /// <summary>
+        /// Get the masked client IP address
+        /// </summary>
+        /// <param name="requestMessage">The HTTP request message.</param>
+        /// <returns>The masked client IP address, if hosted as on OWIN application; otherwise returns null.</returns>
         public static string GetMaskedClientIpAddress(this HttpRequestMessage requestMessage)
         {
             // note that this only works if we are hosted as an OWIN app
             if (requestMessage.Properties.ContainsKey("MS_OwinContext"))
             {
-                OwinContext owinContext = requestMessage.Properties["MS_OwinContext"] as OwinContext;
-                if (owinContext != null)
+                if (requestMessage.Properties["MS_OwinContext"] is OwinContext owinContext)
                 {
                     string remoteIpAddress = owinContext.Request.RemoteIpAddress;
 
                     string maskedRemoteIpAddress = string.Empty;
 
-                    IPAddress remoteIp = null;
-
-                    if (IPAddress.TryParse(remoteIpAddress, out remoteIp))
+                    if (IPAddress.TryParse(remoteIpAddress, out IPAddress remoteIp))
                     {
                         byte[] addressBytes = remoteIp.GetAddressBytes();
                         if (remoteIp.AddressFamily == AddressFamily.InterNetwork)
@@ -230,6 +227,12 @@ public static string GetMaskedClientIpAddress(this HttpRequestMessage requestMes
         }
 #endif
 
+        /// <summary>
+        /// Append a key value pair to a non-null <see cref="StringBuilder"/>.
+        /// </summary>
+        /// <param name="builder">The StringBuilder to append the key value pair to.</param>
+        /// <param name="name">The key to be appended to the StringBuilder.</param>
+        /// <param name="value">The value to be appended to the StringBuilder.</param>
         public static void AppendKeyValuePairIfNotEmpty(this StringBuilder builder, string name, object value)
         {
             if (value != null)