PnP doc comment updates

iothub/device/src/DeviceClient.ConventionBasedOperations.cs

@@ -19,7 +19,7 @@ public partial class DeviceClient : IDisposable
 #endif
     {
         /// <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;
 
@@ -28,15 +28,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>
@@ -50,7 +50,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);
 
@@ -61,16 +61,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);

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;
@@ -50,7 +50,8 @@ public override T ConvertFromObject<T>(object objectToConvert)
         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 +63,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 +74,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>

shared/src/PayloadSerializer.cs

@@ -7,18 +7,21 @@ namespace Microsoft.Azure.Devices.Shared
     /// Provides the serialization for a specified convention.
     /// </summary>
     /// <remarks>
-    /// The serializer is responsible for converting all of your objects into the correct format for the <see cref="PayloadConvention"/> that uses it.
+    /// The serializer is responsible for converting all objects into the correct format for the <see cref="PayloadConvention"/> that uses it.
     /// <para>
-    /// By default we have implemented the <see cref="NewtonsoftJsonPayloadSerializer"/> class that uses <see cref="Newtonsoft.Json.JsonConvert"/>
+    /// By default there are implementions the <see cref="NewtonsoftJsonPayloadSerializer"/> class that uses <see cref="Newtonsoft.Json.JsonConvert"/>
     /// to handle the serialization for the <see cref="DefaultPayloadConvention"/> class.
     /// </para>
     /// </remarks>
     public abstract class PayloadSerializer
     {
         /// <summary>
-        /// Used to specify what type of content to expect.
+        /// Used to specify what type of content will be in the payload.
         /// </summary>
-        /// <remarks>This can be free-form but should adhere to standard MIME types. For example, "application/json" is what we implement by default.</remarks>
+        /// <remarks>
+        /// This can be free-form but should adhere to standard <see href="https://docs.w3cub.com/http/basics_of_http/mime_types.html">MIME types</see>,
+        /// for example: "application/json".
+        /// </remarks>
         /// <value>A string representing the content type to use when sending a payload.</value>
         public abstract string ContentType { get; }
 
@@ -32,17 +35,19 @@ public abstract class PayloadSerializer
         /// <summary>
         /// Convert the serialized string to an object.
         /// </summary>
-        /// <typeparam name="T">The type you want to return.</typeparam>
-        /// <param name="stringToDeserialize">String to deserialize.</param>
+        /// <typeparam name="T">The type to return.</typeparam>
+        /// <param name="stringToDeserialize">The string to deserialize.</param>
         /// <returns>A fully deserialized type.</returns>
         public abstract T DeserializeToType<T>(string stringToDeserialize);
 
         /// <summary>
         /// Converts the object using the serializer.
         /// </summary>
-        /// <remarks>This class is used by the PayloadCollection-based classes to attempt to convert from the native serializer type
+        /// <remarks>
+        /// This class is used by the PayloadCollection-based classes to attempt to convert from the native serializer type
         /// (for example, JObject or JsonElement) to the desired type.
-        /// When you implement this you need to be aware of what type your serializer will use for anonymous types.</remarks>
+        /// When implementing this, be aware of what type the serializer will use for anonymous types.
+        /// </remarks>
         /// <typeparam name="T">The type to convert to.</typeparam>
         /// <param name="objectToConvert">The object to convert.</param>
         /// <returns>A converted object</returns>
@@ -52,15 +57,15 @@ public abstract class PayloadSerializer
         /// Gets a nested property from the serialized data.
         /// </summary>
         /// <remarks>
-        /// This is used internally by our PayloadCollection-based classes to attempt to get a property of the underlying object.
+        /// This is used by the PayloadCollection-based classes to attempt to get a property of the underlying object.
         /// An example of this would be a property under the component.
         /// </remarks>
         /// <typeparam name="T">The type to convert the retrieved property to.</typeparam>
         /// <param name="nestedObject">The object that might contain the nested property.
         /// This needs to be in the json object equivalent format as required by the serializer or the string representation of it.</param>
         /// <param name="propertyName">The name of the property to be retrieved.</param>
-        /// <returns>True if the nested object contains an element with the specified key; otherwise, it returns false.</returns>
-        /// <param name="outValue"></param>
+        /// <param name="outValue">The retrieved value.</param>
+        /// <returns>True if the nested object contains an element with the specified key, otherwise false.</returns>
         public abstract bool TryGetNestedObjectValue<T>(object nestedObject, string propertyName, out T outValue);
 
         /// <summary>
@@ -69,7 +74,7 @@ public abstract class PayloadSerializer
         /// <param name="value">The value of the property.</param>
         /// <param name="statusCode">The status code of the write operation.</param>
         /// <param name="version">The version the property is responding to.</param>
-        /// <param name="description">An optional description of the writable property response.</param>
+        /// <param name="description">An optional response description to the writable property request.</param>
         /// <returns>The writable property response to be used with this serializer.</returns>
         public abstract IWritablePropertyResponse CreateWritablePropertyResponse(object value, int statusCode, long version, string description = default);
     }

shared/src/Utf8PayloadEncoder.cs

@@ -6,14 +6,14 @@
 namespace Microsoft.Azure.Devices.Shared
 {
     /// <summary>
-    /// A UTF-8 <see cref="PayloadEncoder"/> implementation.
+    /// A UTF-8 PayloadEncoder implementation.
     /// </summary>
     public class Utf8PayloadEncoder : PayloadEncoder
     {
         /// <summary>
         /// The default instance of this class.
         /// </summary>
-        public static readonly Utf8PayloadEncoder Instance = new Utf8PayloadEncoder();
+        public static Utf8PayloadEncoder Instance { get; } = new Utf8PayloadEncoder();
 
         /// <inheritdoc/>
         public override Encoding ContentEncoding => Encoding.UTF8;