PnP doc comment updates

iothub/device/src/DeviceClient.ConventionBasedOperations.cs

@@ -16,7 +16,7 @@ namespace Microsoft.Azure.Devices.Client
     public partial class DeviceClient : IDisposable
     {
         /// <summary>
-        /// The <see cref="PayloadConvention"/> that the client uses for convention-based operations.
+        /// The payload convention implementation that the client uses for convention-based operations.
         /// </summary>
         public PayloadConvention PayloadConvention => InternalClient.PayloadConvention;
 
@@ -25,15 +25,15 @@ public partial class DeviceClient : IDisposable
         /// </summary>
         /// <remarks>
         /// Use the <see cref="TelemetryMessage(string)"/> constructor to pass in the optional component name
-        /// that the telemetry message is from.
+        /// that the telemetry message belongs to.
         /// </remarks>
         /// <param name="telemetryMessage">The telemetry message.</param>
         /// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
         public Task SendTelemetryAsync(TelemetryMessage telemetryMessage, CancellationToken cancellationToken = default)
             => InternalClient.SendTelemetryAsync(telemetryMessage, cancellationToken);
 
         /// <summary>
-        /// Set the global command callback handler.
+        /// Set the command callback handler.
         /// </summary>
         /// <param name="callback">A method implementation that will handle the incoming command.</param>
         /// <param name="userContext">Generic parameter to be interpreted by the client code.</param>
@@ -47,7 +47,7 @@ public Task SubscribeToCommandsAsync(
         /// Retrieve the client properties.
         /// </summary>
         /// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
-        /// <returns>The device properties.</returns>
+        /// <returns>The client properties.</returns>
         public Task<ClientProperties> GetClientPropertiesAsync(CancellationToken cancellationToken = default)
             => InternalClient.GetClientTwinPropertiesAsync(cancellationToken);
 
@@ -58,16 +58,21 @@ public Task<ClientProperties> GetClientPropertiesAsync(CancellationToken cancell
         /// <param name="propertyCollection">Reported properties to push.</param>
         /// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
         /// <returns>The response of the update operation.</returns>
-        public Task<ClientPropertiesUpdateResponse> UpdateClientPropertiesAsync(ClientPropertyCollection propertyCollection, CancellationToken cancellationToken = default)
+        public Task<ClientPropertiesUpdateResponse> UpdateClientPropertiesAsync(
+            ClientPropertyCollection propertyCollection,
+            CancellationToken cancellationToken = default)
             => InternalClient.UpdateClientPropertiesAsync(propertyCollection, cancellationToken);
 
         /// <summary>
-        /// Sets the global listener for writable property update events.
+        /// Sets the listener for writable property update events.
         /// </summary>
-        /// <param name="callback">The global call back to handle all writable property updates.</param>
+        /// <param name="callback">The callback to handle all writable property updates.</param>
         /// <param name="userContext">Generic parameter to be interpreted by the client code.</param>
         /// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
-        public Task SubscribeToWritablePropertyUpdateRequestsAsync(Func<ClientPropertyCollection, object, Task> callback, object userContext, CancellationToken cancellationToken = default)
+        public Task SubscribeToWritablePropertyUpdateRequestsAsync(
+            Func<ClientPropertyCollection, object, Task> callback,
+            object userContext,
+            CancellationToken cancellationToken = default)
             => InternalClient.SubscribeToWritablePropertyUpdateRequestsAsync(callback, userContext, cancellationToken);
     }
 }

iothub/device/src/PayloadCollection.cs

@@ -28,18 +28,16 @@ public abstract class PayloadCollection : IEnumerable<KeyValuePair<string, objec
         public PayloadConvention Convention { get; internal set; }
 
         /// <summary>
-        /// Get the value at the specified key.
+        /// Gets the value with the specified key.
         /// </summary>
         /// <remarks>
         /// This accessor is best used to access and cast to simple types.
         /// It is recommended to use <see cref="TryGetValue"/> to deserialize to a complex type.
         /// <para>
-        /// <remarks>
         /// For setting component-level property values see <see cref="ClientPropertyCollection.AddComponentProperty(string, string, object)"/>
-        /// and <see cref="ClientPropertyCollection.AddComponentProperties(string, IDictionary{string, object})"/> instead.
-        /// These convenience methods ensure that component-level properties include the component identifier markers { "__t": "c" }.
+        /// and <see cref="ClientPropertyCollection.AddComponentProperties(string, IDictionary{string, object})"/> instead
+        /// as these convenience methods ensure that component-level properties include the component identifier markers: { "__t": "c" }.
         /// For more information see <see href="https://docs.microsoft.com/azure/iot-pnp/concepts-convention#sample-multiple-components-read-only-property"/>.
-        /// </remarks>
         /// </para>
         /// </remarks>
         /// <param name="key">Key of value.</param>
@@ -73,8 +71,8 @@ public virtual void Add(string key, object value)
         /// For property operations see <see cref="ClientPropertyCollection.AddOrUpdateRootProperty(string, object)"/>
         /// and <see cref="ClientPropertyCollection.AddOrUpdateComponentProperties(string, IDictionary{string, object})"/> instead.
         /// </remarks>
-        /// <param name="key">The name of the telemetry.</param>
-        /// <param name="value">The value of the telemetry.</param>
+        /// <param name="key">The name of the key to be added to the collection.</param>
+        /// <param name="value">The value to be added to the collection.</param>
         /// <exception cref="ArgumentNullException"><paramref name="key"/> is <c>null</c>.</exception>
         public virtual void AddOrUpdate(string key, object value)
         {
@@ -95,10 +93,10 @@ public virtual byte[] GetPayloadObjectBytes()
         }
 
         /// <summary>
-        /// Determines whether the specified property is present.
+        /// Determines whether the specified key is present.
         /// </summary>
         /// <param name="key">The key in the collection to locate.</param>
-        /// <returns><c>true</c> if the specified property is present; otherwise, <c>false</c>.</returns>
+        /// <returns><c>true</c> if the specified property is present, otherwise <c>false</c>.</returns>
         public bool Contains(string key)
         {
             return Collection.ContainsKey(key);
@@ -114,6 +112,8 @@ public bool Contains(string key)
         /// <returns>True if a value of type <c>T</c> with the specified key was found; otherwise, it returns false.</returns>
         public bool TryGetValue<T>(string key, out T value)
         {
+            value = default;
+
             if (Logging.IsEnabled && Convention == null)
             {
                 Logging.Info(this, $"The convention for this collection is not set; this typically means this collection was not created by the client. " +
@@ -123,7 +123,6 @@ public bool TryGetValue<T>(string key, out T value)
             // If the key is null, empty or whitespace, then return false with the default value of the type <T> passed in.
             if (string.IsNullOrWhiteSpace(key))
             {
-                value = default;
                 return false;
             }
 
@@ -145,7 +144,6 @@ public bool TryGetValue<T>(string key, out T value)
                 // If the value associated with the key is null, then return true with the default value of the type <T> passed in.
                 if (retrievedPropertyValue == null)
                 {
-                    value = default;
                     return true;
                 }
 
@@ -175,12 +173,14 @@ public bool TryGetValue<T>(string key, out T value)
                     {
                         // Case 3a:
                         // Check if the retrieved value is a writable property update acknowledgment
-                        var newtonsoftWritablePropertyResponse = Convention.PayloadSerializer.ConvertFromObject<NewtonsoftJsonWritablePropertyResponse>(retrievedPropertyValue);
+                        var newtonsoftWritablePropertyResponse = Convention.PayloadSerializer
+                            .ConvertFromObject<NewtonsoftJsonWritablePropertyResponse>(retrievedPropertyValue);
 
                         if (typeof(IWritablePropertyResponse).IsAssignableFrom(typeof(T)))
                         {
-                            // If T is IWritablePropertyResponse the property value should be of type IWritablePropertyResponse as defined in the PayloadSerializer.
-                            // We'll convert the json object to NewtonsoftJsonWritablePropertyResponse and then convert it to the appropriate IWritablePropertyResponse object.
+                            // If T is IWritablePropertyResponse the property value should be of type IWritablePropertyResponse as
+                            // defined in the PayloadSerializer. We'll convert the json object to NewtonsoftJsonWritablePropertyResponse
+                            // and then convert it to the appropriate IWritablePropertyResponse object.
                             value = (T)Convention.PayloadSerializer.CreateWritablePropertyResponse(
                                 newtonsoftWritablePropertyResponse.Value,
                                 newtonsoftWritablePropertyResponse.AckCode,
@@ -189,7 +189,7 @@ public bool TryGetValue<T>(string key, out T value)
                             return true;
                         }
 
-                        var writablePropertyValue = newtonsoftWritablePropertyResponse.Value;
+                        object writablePropertyValue = newtonsoftWritablePropertyResponse.Value;
 
                         // If the object is of type T or can be cast or converted to type T, go ahead and return it.
                         if (ObjectConversionHelpers.TryCastOrConvert(writablePropertyValue, Convention, out value))
@@ -215,7 +215,6 @@ public bool TryGetValue<T>(string key, out T value)
                 }
             }
 
-            value = default;
             return false;
         }
 

shared/src/ConventionBasedConstants.cs

@@ -4,7 +4,7 @@
 namespace Microsoft.Azure.Devices.Shared
 {
     /// <summary>
-    /// Container for common convention based constants.
+    /// Common convention based constants.
     /// </summary>
     public static class ConventionBasedConstants
     {
@@ -29,17 +29,17 @@ public static class ConventionBasedConstants
         public const string ValuePropertyName = "value";
 
         /// <summary>
-        /// Represents the JSON document property name for the Ack Code of a writable property response.
+        /// Represents the JSON document property name for the acknowledgement code of a writable property response.
         /// </summary>
         public const string AckCodePropertyName = "ac";
 
         /// <summary>
-        /// Represents the JSON document property name for the Ack Version of a writable property response.
+        /// Represents the JSON document property name for the acknowledgement version of a writable property response.
         /// </summary>
         public const string AckVersionPropertyName = "av";
 
         /// <summary>
-        /// Represents the JSON document property name for the Ack Description of a writable property response.
+        /// Represents the JSON document property name for the acknowledgement description of a writable property response.
         /// </summary>
         public const string AckDescriptionPropertyName = "ad";
     }

shared/src/DefaultPayloadConvention.cs

@@ -14,7 +14,7 @@ public sealed class DefaultPayloadConvention : PayloadConvention
         /// <summary>
         /// A static instance of this class.
         /// </summary>
-        public static readonly DefaultPayloadConvention Instance = new DefaultPayloadConvention();
+        public static DefaultPayloadConvention Instance { get; } = new DefaultPayloadConvention();
 
         /// <inheritdoc/>
         public override PayloadSerializer PayloadSerializer { get; } = NewtonsoftJsonPayloadSerializer.Instance;

shared/src/NewtonsoftJsonPayloadSerializer.cs

@@ -7,7 +7,7 @@
 namespace Microsoft.Azure.Devices.Shared
 {
     /// <summary>
-    /// A <see cref="JsonConvert"/> <see cref="PayloadSerializer"/> implementation.
+    /// A <see cref="JsonConvert"/> PayloadSerializer implementation.
     /// </summary>
     public class NewtonsoftJsonPayloadSerializer : PayloadSerializer
     {
@@ -19,7 +19,7 @@ public class NewtonsoftJsonPayloadSerializer : PayloadSerializer
         /// <summary>
         /// The default instance of this class.
         /// </summary>
-        public static readonly NewtonsoftJsonPayloadSerializer Instance = new NewtonsoftJsonPayloadSerializer();
+        public static NewtonsoftJsonPayloadSerializer Instance { get; } = new NewtonsoftJsonPayloadSerializer();
 
         /// <inheritdoc/>
         public override string ContentType => ApplicationJson;
@@ -39,18 +39,23 @@ public override T DeserializeToType<T>(string stringToDeserialize)
         /// <inheritdoc/>
         public override T ConvertFromObject<T>(object objectToConvert)
         {
-            var token = JToken.FromObject(objectToConvert);
+            if (objectToConvert == null)
+            {
+                return default;
+            }
 
-            return objectToConvert == null
+            var jToken = JToken.FromObject(objectToConvert);
+            return jToken == null
                 ? default
-                : token.ToObject<T>();
+                : jToken.ToObject<T>();
         }
 
         /// <inheritdoc/>
         public override bool TryGetNestedObjectValue<T>(object nestedObject, string propertyName, out T outValue)
         {
             outValue = default;
-            if (nestedObject == null || string.IsNullOrEmpty(propertyName))
+            if (nestedObject == null
+                || string.IsNullOrEmpty(propertyName))
             {
                 return false;
             }
@@ -62,7 +67,8 @@ public override bool TryGetNestedObjectValue<T>(object nestedObject, string prop
                     ? DeserializeToType<JObject>((string)nestedObject)
                     : nestedObject as JObject;
 
-                if (nestedObjectAsJObject != null && nestedObjectAsJObject.TryGetValue(propertyName, out JToken element))
+                if (nestedObjectAsJObject != null
+                    && nestedObjectAsJObject.TryGetValue(propertyName, out JToken element))
                 {
                     outValue = element.ToObject<T>();
                     return true;
@@ -72,6 +78,7 @@ public override bool TryGetNestedObjectValue<T>(object nestedObject, string prop
             {
                 // Catch and ignore any exceptions caught
             }
+
             return false;
         }
 

shared/src/PayloadConvention.cs

@@ -6,9 +6,11 @@ namespace Microsoft.Azure.Devices.Shared
     /// <summary>
     /// The payload convention class.
     /// </summary>
-    /// <remarks>The payload convention is used to define a specific serializer as well as a specific content encoding.
-    /// For example, IoT has a <see href="https://docs.microsoft.com/azure/iot-pnp/concepts-convention">convention</see> that is designed
-    /// to make it easier to get started with products that use specific conventions by default.</remarks>
+    /// <remarks>
+    /// The payload convention is used to define a specific serializer as well as a specific content encoding.
+    /// For example, Azure IoT has a <see href="https://docs.microsoft.com/azure/iot-pnp/concepts-convention">Plug and Play convention</see>
+    /// that is designed to make it easier to get started with products that use specific conventions by default.
+    /// </remarks>
     public abstract class PayloadConvention
     {
         /// <summary>
@@ -26,8 +28,8 @@ public abstract class PayloadConvention
         /// <summary>
         /// Returns the byte array for the convention-based message.
         /// </summary>
-        /// <remarks>This base class will use the <see cref="PayloadSerializer"/> and <see cref="PayloadEncoder"/> to create this byte array.</remarks>
-        /// <param name="objectToSendWithConvention">The convention-based message that is to be sent.</param>
+        /// <remarks>This will use the <see cref="PayloadSerializer"/> and <see cref="PayloadEncoder"/> to create the byte array.</remarks>
+        /// <param name="objectToSendWithConvention">The convention-based message to be sent.</param>
         /// <returns>The correctly encoded object for this convention.</returns>
         public virtual byte[] GetObjectBytes(object objectToSendWithConvention)
         {

shared/src/PayloadEncoder.cs

@@ -6,12 +6,12 @@
 namespace Microsoft.Azure.Devices.Shared
 {
     /// <summary>
-    /// This class specifies the byte encoding for the payload.
+    /// Specifies the byte encoding for the payload.
     /// </summary>
     /// <remarks>
-    /// The encoder is responsible for encoding all of your objects into the correct bytes for the <see cref="PayloadConvention"/> that uses it.
+    /// The encoder is responsible for encoding all objects into the correct bytes for the <see cref="PayloadConvention"/> that uses it.
     /// <para>
-    /// By default we have implemented the <see cref="Utf8PayloadEncoder"/> class that uses <see cref="System.Text.Encoding.UTF8"/>
+    /// By default, there are implementations of the <see cref="Utf8PayloadEncoder"/> class that uses <see cref="Encoding.UTF8"/>
     /// to handle the encoding for the <see cref="DefaultPayloadConvention"/> class.
     /// </para>
     /// </remarks>