fix up some docs (#5177)

src/Libraries/Microsoft.Extensions.Diagnostics.ResourceMonitoring/SystemResources.cs

@@ -3,7 +3,7 @@
 namespace Microsoft.Extensions.Diagnostics.ResourceMonitoring;
 
 /// <summary>
-/// CPU and memory limits defined by the underlying system.
+/// Provides information about the CPU and memory limits defined by the underlying system.
 /// </summary>
 #pragma warning disable CA1815 // Override equals and operator equals on value types
 public readonly struct SystemResources
@@ -13,22 +13,22 @@ public readonly struct SystemResources
     /// Gets the CPU units available in the system.
     /// </summary>
     /// <remarks>
-    /// This value corresponds to the number of the guaranteed CPUs as described by Kubernetes CPU request parameter, each 1000 CPU units
-    /// represent 1 CPU or 1 Core. For example, if the POD is configured with 1500m units as the CPU request, this property will be assigned
-    /// to 1.5 which means one and a half CPU will be dedicated for the POD.
-    /// For POD this value is calculated based on the cgroupv2 weight, using the formula.
-    /// y = (1 + ((x - 2) * 9999) / 262142), where y is the CPU weight and x is the CPU share (cgroup v1).
-    /// https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/2254-cgroup-v2#phase-1-convert-from-cgroups-v1-settings-to-v2.
+    /// This value corresponds to the number of the guaranteed CPUs as described by Kubernetes CPU request parameter. Each 1000 CPU units
+    /// represent 1 CPU or 1 Core. For example, if the Pod is configured with 1500m units as the CPU request, this property will be assigned
+    /// to 1.5, which means one and a half CPU will be dedicated for the Pod.
+    /// For a Pod, this value is calculated based on the <c>cgroupv2</c> weight, using the formula
+    /// <c>y = (1 + ((x - 2) * 9999) / 262142)</c>, where <c>y</c> is the CPU weight and <c>x</c> is the CPU share (<c>cgroup v1</c>).
+    /// For more information, see <see href="https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/2254-cgroup-v2#phase-1-convert-from-cgroups-v1-settings-to-v2"/>.
     /// </remarks>
     public double GuaranteedCpuUnits { get; }
 
     /// <summary>
     /// Gets the maximum CPU units available in the system.
     /// </summary>
     /// <remarks>
-    /// This value corresponds to the number of the maximum CPUs as described by Kubernetes CPU limit parameter, each 1000 CPU units
-    /// represent 1 CPU or 1 Core. For example, if the is configured with 1500m units as the CPU limit, this property will be assigned
-    /// to 1.5 which means one and a half CPU will be the maximum CPU available.
+    /// This value corresponds to the number of the maximum CPUs as described by Kubernetes CPU limit parameter. Each 1000 CPU units
+    /// represent 1 CPU or 1 Core. For example, if the Pod is configured with 1500m units as the CPU limit, this property will be assigned
+    /// to 1.5, which means one and a half CPU will be the maximum CPU available.
     /// </remarks>
     public double MaximumCpuUnits { get; }
 
@@ -38,7 +38,7 @@ public readonly struct SystemResources
     public ulong GuaranteedMemoryInBytes { get; }
 
     /// <summary>
-    /// Gets the Container's Request Memory Limit or the Maximum allocated for the VM.
+    /// Gets the container's request memory limit or the maximum allocated for the VM.
     /// </summary>
     public ulong MaximumMemoryInBytes { get; }
 

src/Libraries/Microsoft.Extensions.Http.Resilience/Hedging/HttpHedgingStrategyOptions.cs

@@ -8,16 +8,16 @@
 namespace Microsoft.Extensions.Http.Resilience;
 
 /// <summary>
-/// Implementation of the <see cref="HedgingStrategyOptions{TResult}"/> for <see cref="HttpResponseMessage"/> results.
+/// Implementation of the <see cref="HedgingStrategyOptions{TResult}"/> class for <see cref="HttpResponseMessage"/> results.
 /// </summary>
 public class HttpHedgingStrategyOptions : HedgingStrategyOptions<HttpResponseMessage>
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="HttpHedgingStrategyOptions"/> class.
     /// </summary>
     /// <remarks>
-    /// By default, the options is set to handle only transient failures,
-    /// i.e. timeouts, 5xx responses and <see cref="HttpRequestException"/> exceptions.
+    /// By default, the options are set to handle only transient failures,
+    /// that is, timeouts, 5xx responses, and <see cref="HttpRequestException"/> exceptions.
     /// </remarks>
     public HttpHedgingStrategyOptions()
     {

src/Libraries/Microsoft.Extensions.Options.Contextual/IContextualOptions.cs

@@ -7,10 +7,10 @@
 namespace Microsoft.Extensions.Options.Contextual;
 
 /// <summary>
-/// Used to retrieve configured <typeparamref name="TOptions"/> instances.
+/// Provides functionality to retrieve configured <typeparamref name="TOptions"/> instances.
 /// </summary>
 /// <typeparam name="TOptions">The type of options being requested.</typeparam>
-/// <typeparam name="TContext">A type defining the context for this request.</typeparam>
+/// <typeparam name="TContext">A type that defines the context for this request.</typeparam>
 public interface IContextualOptions<TOptions, TContext>
     where TOptions : class
     where TContext : IOptionsContext

src/Libraries/Microsoft.Extensions.Options.Contextual/INamedContextualOptions.cs

@@ -7,7 +7,7 @@
 namespace Microsoft.Extensions.Options.Contextual;
 
 /// <summary>
-/// Used to retrieve named configured <typeparamref name="TOptions"/> instances.
+/// Provides functionality to retrieve named configured <typeparamref name="TOptions"/> instances.
 /// </summary>
 /// <typeparam name="TOptions">The type of options being requested.</typeparam>
 /// <typeparam name="TContext">A type defining the context for this request.</typeparam>

src/Libraries/Microsoft.Extensions.Options.Contextual/Provider/IConfigureContextualOptions.cs

@@ -6,14 +6,14 @@
 namespace Microsoft.Extensions.Options.Contextual.Provider;
 
 /// <summary>
-/// Represents something that configures the <typeparamref name="TOptions"/> type.
+/// Provides functionality to configure the <typeparamref name="TOptions"/> type.
 /// </summary>
 /// <typeparam name="TOptions">The type of options configured.</typeparam>
 public interface IConfigureContextualOptions<in TOptions> : IDisposable
     where TOptions : class
 {
     /// <summary>
-    /// Invoked to configure a <typeparamref name="TOptions"/> instance.
+    /// Configures a <typeparamref name="TOptions"/> instance.
     /// </summary>
     /// <param name="options">The options instance to configure.</param>
     void Configure(TOptions options);

src/Libraries/Microsoft.Extensions.Options.Contextual/Provider/ILoadContextualOptions.cs

@@ -7,7 +7,7 @@
 namespace Microsoft.Extensions.Options.Contextual.Provider;
 
 /// <summary>
-/// Used to retrieve named configuration data from a contextual options provider implementation.
+/// Provides functionality to retrieve named configuration data from a contextual options provider implementation.
 /// </summary>
 /// <typeparam name="TOptions">The type of options configured.</typeparam>
 public interface ILoadContextualOptions<TOptions>

src/Libraries/Microsoft.Extensions.Options.Contextual/Provider/IOptionsContextReceiver.cs

@@ -4,12 +4,12 @@
 namespace Microsoft.Extensions.Options.Contextual.Provider;
 
 /// <summary>
-/// Used by contextual options providers to collect context data.
+/// Provides functionality for contextual options providers to collect context data.
 /// </summary>
 public interface IOptionsContextReceiver
 {
     /// <summary>
-    /// Add a key-value pair to the context.
+    /// Adds a key-value pair to the context.
     /// </summary>
     /// <typeparam name="T">The type of the data.</typeparam>
     /// <param name="key">The name of the data.</param>

src/Libraries/Microsoft.Extensions.Options.Contextual/Provider/NullConfigureContextualOptions.cs

@@ -4,7 +4,7 @@
 namespace Microsoft.Extensions.Options.Contextual.Provider;
 
 /// <summary>
-/// Helper class.
+/// Provides helper methods for a configuration context. This class can't be inherited.
 /// </summary>
 public static class NullConfigureContextualOptions
 {

src/Libraries/Microsoft.Extensions.Options.Contextual/Provider/NullConfigureContextualOptions_1.cs

@@ -6,7 +6,7 @@ namespace Microsoft.Extensions.Options.Contextual.Provider;
 #pragma warning disable SA1649 // File name should match first type name
 
 /// <summary>
-/// A do-nothing implementation of <see cref="IConfigureContextualOptions{TOptions}"/>.
+/// Implements <see cref="IConfigureContextualOptions{TOptions}"/> but does nothing.
 /// </summary>
 /// <typeparam name="TOptions">The options type to configure.</typeparam>
 internal sealed class NullConfigureContextualOptions<TOptions> : IConfigureContextualOptions<TOptions>