Doc updates (#108722)

Author: gewarren

src/libraries/Microsoft.Extensions.Configuration.Ini/src/IniConfigurationExtensions.cs

@@ -31,7 +31,7 @@ public static IConfigurationBuilder AddIniFile(this IConfigurationBuilder builde
         /// <param name="builder">The <see cref="IConfigurationBuilder"/> to add to.</param>
         /// <param name="path">The path relative to the base path stored in
         /// <see cref="IConfigurationBuilder.Properties"/> of <paramref name="builder"/>.</param>
-        /// <param name="optional">Whether the file is optional.</param>
+        /// <param name="optional"><see langword="true"/> if the file is optional; otherwise, <see langword="false"/> .</param>
         /// <returns>The <see cref="IConfigurationBuilder"/>.</returns>
         public static IConfigurationBuilder AddIniFile(this IConfigurationBuilder builder, string path, bool optional)
         {
@@ -45,7 +45,7 @@ public static IConfigurationBuilder AddIniFile(this IConfigurationBuilder builde
         /// <param name="path">Path relative to the base path stored in
         /// <see cref="IConfigurationBuilder.Properties"/> of <paramref name="builder"/>.</param>
         /// <param name="optional"><see langword="true"/> if the file is optional; otherwise, <see langword="false"/>.</param>
-        /// <param name="reloadOnChange">Whether the configuration should be reloaded if the file changes; otherwise, <see langword="false"/>.</param>
+        /// <param name="reloadOnChange"><see langword="true"/> if the configuration should be reloaded if the file changes; otherwise, <see langword="false"/>.</param>
         /// <returns>The <see cref="IConfigurationBuilder"/>.</returns>
         public static IConfigurationBuilder AddIniFile(this IConfigurationBuilder builder, string path, bool optional, bool reloadOnChange)
         {

src/libraries/System.Formats.Nrbf/src/System/Formats/Nrbf/PayloadOptions.cs

@@ -6,7 +6,7 @@
 namespace System.Formats.Nrbf;
 
 /// <summary>
-/// Defines a variety of configuration options for decoding NRBF payloads.
+/// Defines configuration options for decoding NRBF payloads.
 /// </summary>
 public sealed class PayloadOptions
 {
@@ -21,9 +21,9 @@ public PayloadOptions() { }
     public TypeNameParseOptions? TypeNameParseOptions { get; set; }
 
     /// <summary>
-    /// Gets or sets a value that indicates whether type name truncation is undone.
+    /// Gets or sets a value that indicates whether type-name truncation is undone.
     /// </summary>
-    /// <value><see langword="true" /> if truncated type names should be reassembled; otherwise, <see langword="false" />.</value>
+    /// <value><see langword="true" /> if truncated type names should be reassembled; otherwise, <see langword="false" />. The default value is <see langword="false" />.</value>
     /// <remarks>
     /// <para>
     /// Example:
@@ -35,7 +35,6 @@ public PayloadOptions() { }
     /// Setting this to <see langword="true" /> can render <see cref="NrbfDecoder"/> susceptible to Denial of Service
     /// attacks when parsing or handling malicious input.
     /// </para>
-    /// <para>The default value is <see langword="false" />.</para>
     /// </remarks>
     public bool UndoTruncatedTypeNames { get; set; }
 }

src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/IncrementalHash.cs

@@ -64,7 +64,7 @@ public void AppendData(byte[] data)
         }
 
         /// <summary>
-        /// Append <paramref name="count"/> bytes of <paramref name="data"/>, starting at <paramref name="offset"/>,
+        /// Appends <paramref name="count"/> bytes of <paramref name="data"/>, starting at <paramref name="offset"/>,
         /// to the data already processed in the hash or HMAC.
         /// </summary>
         /// <param name="data">The data to process.</param>
@@ -113,9 +113,8 @@ public void AppendData(ReadOnlySpan<byte> data)
         }
 
         /// <summary>
-        /// Retrieve the hash or HMAC for the data accumulated from prior calls to
-        /// <see cref="AppendData(byte[])"/>, and return to the state the object
-        /// was in at construction.
+        /// Retrieves the hash or HMAC for the data accumulated from prior calls to
+        /// <see cref="AppendData(byte[])"/>, and resets the object to its initial state.
         /// </summary>
         /// <returns>The computed hash or HMAC.</returns>
         /// <exception cref="ObjectDisposedException">The object has already been disposed.</exception>
@@ -239,7 +238,7 @@ public int GetCurrentHash(Span<byte> destination)
         ///   The buffer to receive the hash or HMAC value.
         /// </param>
         /// <param name="bytesWritten">
-        ///   When this method returns, the total number of bytes written into <paramref name="destination" />.
+        ///   When this method returns, contains the total number of bytes written into <paramref name="destination" />.
         ///   This parameter is treated as uninitialized.
         /// </param>
         /// <returns>
@@ -275,7 +274,7 @@ private int GetCurrentHashCore(Span<byte> destination)
         /// Creates a new instance of <see cref="IncrementalHash" /> with the existing appended data preserved.
         /// </summary>
         /// <returns>A clone of the current instance.</returns>
-        /// <exception cref="CryptographicException">An error has occurred during the operation.</exception>
+        /// <exception cref="CryptographicException">An error occurred during the operation.</exception>
         /// <exception cref="ObjectDisposedException">The object has already been disposed.</exception>
         public IncrementalHash Clone()
         {
@@ -309,7 +308,7 @@ public void Dispose()
         }
 
         /// <summary>
-        /// Create an <see cref="IncrementalHash"/> for the algorithm specified by <paramref name="hashAlgorithm"/>.
+        /// Creates an <see cref="IncrementalHash"/> for the algorithm specified by <paramref name="hashAlgorithm"/>.
         /// </summary>
         /// <param name="hashAlgorithm">The name of the hash algorithm to perform.</param>
         /// <returns>
@@ -330,15 +329,15 @@ public static IncrementalHash CreateHash(HashAlgorithmName hashAlgorithm)
         }
 
         /// <summary>
-        /// Create an <see cref="IncrementalHash"/> for the Hash-based Message Authentication Code (HMAC)
-        /// algorithm utilizing the hash algorithm specified by <paramref name="hashAlgorithm"/>, and a
+        /// Creates an <see cref="IncrementalHash"/> for the Hash-based Message Authentication Code (HMAC)
+        /// algorithm using the hash algorithm specified by <paramref name="hashAlgorithm"/> and a
         /// key specified by <paramref name="key"/>.
         /// </summary>
         /// <param name="hashAlgorithm">The name of the hash algorithm to perform within the HMAC.</param>
         /// <param name="key">
         ///     The secret key for the HMAC. The key can be any length, but a key longer than the output size
         ///     of the hash algorithm specified by <paramref name="hashAlgorithm"/> will be hashed (using the
-        ///     algorithm specified by <paramref name="hashAlgorithm"/>) to derive a correctly-sized key. Therefore,
+        ///     algorithm specified by <paramref name="hashAlgorithm"/>) to derive a correctly sized key. Therefore,
         ///     the recommended size of the secret key is the output size of the hash specified by
         ///     <paramref name="hashAlgorithm"/>.
         /// </param>
@@ -359,15 +358,15 @@ public static IncrementalHash CreateHMAC(HashAlgorithmName hashAlgorithm, byte[]
         }
 
         /// <summary>
-        /// Create an <see cref="IncrementalHash"/> for the Hash-based Message Authentication Code (HMAC)
-        /// algorithm utilizing the hash algorithm specified by <paramref name="hashAlgorithm"/>, and a
+        /// Creates an <see cref="IncrementalHash"/> for the Hash-based Message Authentication Code (HMAC)
+        /// algorithm using the hash algorithm specified by <paramref name="hashAlgorithm"/> and a
         /// key specified by <paramref name="key"/>.
         /// </summary>
         /// <param name="hashAlgorithm">The name of the hash algorithm to perform within the HMAC.</param>
         /// <param name="key">
         ///     The secret key for the HMAC. The key can be any length, but a key longer than the output size
         ///     of the hash algorithm specified by <paramref name="hashAlgorithm"/> will be hashed (using the
-        ///     algorithm specified by <paramref name="hashAlgorithm"/>) to derive a correctly-sized key. Therefore,
+        ///     algorithm specified by <paramref name="hashAlgorithm"/>) to derive a correctly sized key. Therefore,
         ///     the recommended size of the secret key is the output size of the hash specified by
         ///     <paramref name="hashAlgorithm"/>.
         /// </param>