[release/9.0] Doc updates for source-of-truth assemblies (#107814)

* doc updates

* try to fix build warnings

* Apply suggestions from code review

Co-authored-by: Carlos Sánchez López <1175054+carlossanlop@users.noreply.github.com>

---------

Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Co-authored-by: Carlos Sánchez López <1175054+carlossanlop@users.noreply.github.com>

src/libraries/Microsoft.Extensions.Caching.Abstractions/src/CacheEntryExtensions.cs

@@ -8,7 +8,7 @@
 namespace Microsoft.Extensions.Caching.Memory
 {
     /// <summary>
-    /// Provide extensions methods for <see cref="ICacheEntry"/> operations.
+    /// Provides extensions methods for <see cref="ICacheEntry"/> operations.
     /// </summary>
     public static class CacheEntryExtensions
     {
@@ -27,7 +27,7 @@ public static ICacheEntry SetPriority(
         }
 
         /// <summary>
-        /// Expire the cache entry if the given <see cref="IChangeToken"/> expires.
+        /// Expires the cache entry if the given <see cref="IChangeToken"/> expires.
         /// </summary>
         /// <param name="entry">The <see cref="ICacheEntry"/>.</param>
         /// <param name="expirationToken">The <see cref="IChangeToken"/> that causes the cache entry to expire.</param>
@@ -71,8 +71,8 @@ public static ICacheEntry SetAbsoluteExpiration(
         }
 
         /// <summary>
-        /// Sets how long the cache entry can be inactive (e.g. not accessed) before it will be removed.
-        /// This will not extend the entry lifetime beyond the absolute expiration (if set).
+        /// Sets how long the cache entry can be inactive (for example, not accessed) before it will be removed.
+        /// This method does not extend the entry lifetime beyond the absolute expiration (if set).
         /// </summary>
         /// <param name="entry">The <see cref="ICacheEntry"/>.</param>
         /// <param name="offset">A <see cref="TimeSpan"/> representing a sliding expiration.</param>
@@ -86,7 +86,7 @@ public static ICacheEntry SetSlidingExpiration(
         }
 
         /// <summary>
-        /// The given callback will be fired after the cache entry is evicted from the cache.
+        /// Fires the given callback after the cache entry is evicted from the cache.
         /// </summary>
         /// <param name="entry">The <see cref="ICacheEntry"/>.</param>
         /// <param name="callback">The callback to run after the entry is evicted.</param>
@@ -101,7 +101,7 @@ public static ICacheEntry RegisterPostEvictionCallback(
         }
 
         /// <summary>
-        /// The given callback will be fired after the cache entry is evicted from the cache.
+        /// Fires the given callback after the cache entry is evicted from the cache.
         /// </summary>
         /// <param name="entry">The <see cref="ICacheEntry"/>.</param>
         /// <param name="callback">The callback to run after the entry is evicted.</param>

src/libraries/Microsoft.Extensions.Caching.Abstractions/src/DistributedCacheEntryExtensions.cs

@@ -6,7 +6,7 @@
 namespace Microsoft.Extensions.Caching.Distributed
 {
     /// <summary>
-    /// Extension methods for <see cref="DistributedCacheEntryOptions"/> operations.
+    /// Provides extension methods for <see cref="DistributedCacheEntryOptions"/> operations.
     /// </summary>
     public static class DistributedCacheEntryExtensions
     {

src/libraries/Microsoft.Extensions.Caching.Abstractions/src/DistributedCacheEntryOptions.cs

@@ -53,7 +53,7 @@ public TimeSpan? AbsoluteExpirationRelativeToNow
         }
 
         /// <summary>
-        /// Gets or sets how long a cache entry can be inactive (e.g. not accessed) before it will be removed.
+        /// Gets or sets how long a cache entry can be inactive (for example, not accessed) before it will be removed.
         /// This will not extend the entry lifetime beyond the absolute expiration (if set).
         /// </summary>
         public TimeSpan? SlidingExpiration

src/libraries/Microsoft.Extensions.Caching.Abstractions/src/DistributedCacheExtensions.cs

@@ -19,7 +19,7 @@ public static class DistributedCacheExtensions
         /// <param name="cache">The cache in which to store the data.</param>
         /// <param name="key">The key to store the data in.</param>
         /// <param name="value">The data to store in the cache.</param>
-        /// <exception cref="System.ArgumentNullException">Thrown when <paramref name="key"/> or <paramref name="value"/> is null.</exception>
+        /// <exception cref="System.ArgumentNullException"><paramref name="key"/> or <paramref name="value"/> is null.</exception>
         public static void Set(this IDistributedCache cache, string key, byte[] value)
         {
             ThrowHelper.ThrowIfNull(key);
@@ -36,7 +36,7 @@ public static void Set(this IDistributedCache cache, string key, byte[] value)
         /// <param name="value">The data to store in the cache.</param>
         /// <param name="token">Optional. A <see cref="CancellationToken" /> to cancel the operation.</param>
         /// <returns>A task that represents the asynchronous set operation.</returns>
-        /// <exception cref="System.ArgumentNullException">Thrown when <paramref name="key"/> or <paramref name="value"/> is null.</exception>
+        /// <exception cref="System.ArgumentNullException"><paramref name="key"/> or <paramref name="value"/> is null.</exception>
         public static Task SetAsync(this IDistributedCache cache, string key, byte[] value, CancellationToken token = default(CancellationToken))
         {
             ThrowHelper.ThrowIfNull(key);
@@ -51,7 +51,7 @@ public static void Set(this IDistributedCache cache, string key, byte[] value)
         /// <param name="cache">The cache in which to store the data.</param>
         /// <param name="key">The key to store the data in.</param>
         /// <param name="value">The data to store in the cache.</param>
-        /// <exception cref="System.ArgumentNullException">Thrown when <paramref name="key"/> or <paramref name="value"/> is null.</exception>
+        /// <exception cref="System.ArgumentNullException"><paramref name="key"/> or <paramref name="value"/> is null.</exception>
         public static void SetString(this IDistributedCache cache, string key, string value)
         {
             cache.SetString(key, value, new DistributedCacheEntryOptions());
@@ -64,7 +64,7 @@ public static void SetString(this IDistributedCache cache, string key, string va
         /// <param name="key">The key to store the data in.</param>
         /// <param name="value">The data to store in the cache.</param>
         /// <param name="options">The cache options for the entry.</param>
-        /// <exception cref="System.ArgumentNullException">Thrown when <paramref name="key"/> or <paramref name="value"/> is null.</exception>
+        /// <exception cref="System.ArgumentNullException"><paramref name="key"/> or <paramref name="value"/> is null.</exception>
         public static void SetString(this IDistributedCache cache, string key, string value, DistributedCacheEntryOptions options)
         {
             ThrowHelper.ThrowIfNull(key);
@@ -81,7 +81,7 @@ public static void SetString(this IDistributedCache cache, string key, string va
         /// <param name="value">The data to store in the cache.</param>
         /// <param name="token">Optional. A <see cref="CancellationToken" /> to cancel the operation.</param>
         /// <returns>A task that represents the asynchronous set operation.</returns>
-        /// <exception cref="System.ArgumentNullException">Thrown when <paramref name="key"/> or <paramref name="value"/> is null.</exception>
+        /// <exception cref="System.ArgumentNullException"><paramref name="key"/> or <paramref name="value"/> is null.</exception>
         public static Task SetStringAsync(this IDistributedCache cache, string key, string value, CancellationToken token = default(CancellationToken))
         {
             return cache.SetStringAsync(key, value, new DistributedCacheEntryOptions(), token);
@@ -96,7 +96,7 @@ public static void SetString(this IDistributedCache cache, string key, string va
         /// <param name="options">The cache options for the entry.</param>
         /// <param name="token">Optional. A <see cref="CancellationToken" /> to cancel the operation.</param>
         /// <returns>A task that represents the asynchronous set operation.</returns>
-        /// <exception cref="System.ArgumentNullException">Thrown when <paramref name="key"/> or <paramref name="value"/> is null.</exception>
+        /// <exception cref="System.ArgumentNullException"><paramref name="key"/> or <paramref name="value"/> is null.</exception>
         public static Task SetStringAsync(this IDistributedCache cache, string key, string value, DistributedCacheEntryOptions options, CancellationToken token = default(CancellationToken))
         {
             ThrowHelper.ThrowIfNull(key);

src/libraries/Microsoft.Extensions.Caching.Abstractions/src/EvictionReason.cs

@@ -4,7 +4,7 @@
 namespace Microsoft.Extensions.Caching.Memory
 {
     /// <summary>
-    /// Specify the reasons why an entry was evicted from the cache.
+    /// Specifies the reasons why an entry was evicted from the cache.
     /// </summary>
     public enum EvictionReason
     {

src/libraries/Microsoft.Extensions.Caching.Abstractions/src/Hybrid/HybridCache.cs

@@ -22,7 +22,7 @@ public abstract class HybridCache
     /// <typeparam name="TState">The type of additional state required by <paramref name="factory"/>.</typeparam>
     /// <typeparam name="T">The type of the data being considered.</typeparam>
     /// <param name="key">The key of the entry to look for or create.</param>
-    /// <param name="factory">Provides the underlying data service is the data is not available in the cache.</param>
+    /// <param name="factory">Provides the underlying data service if the data is not available in the cache.</param>
     /// <param name="state">The state required for <paramref name="factory"/>.</param>
     /// <param name="options">Additional options for this cache entry.</param>
     /// <param name="tags">The tags to associate with this cache item.</param>
@@ -36,7 +36,7 @@ public abstract ValueTask<T> GetOrCreateAsync<TState, T>(string key, TState stat
     /// </summary>
     /// <typeparam name="T">The type of the data being considered.</typeparam>
     /// <param name="key">The key of the entry to look for or create.</param>
-    /// <param name="factory">Provides the underlying data service is the data is not available in the cache.</param>
+    /// <param name="factory">Provides the underlying data service if the data is not available in the cache.</param>
     /// <param name="options">Additional options for this cache entry.</param>
     /// <param name="tags">The tags to associate with this cache item.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> used to propagate notifications that the operation should be canceled.</param>

src/libraries/Microsoft.Extensions.Caching.Abstractions/src/Hybrid/HybridCacheEntryOptions.cs

@@ -7,10 +7,10 @@
 namespace Microsoft.Extensions.Caching.Hybrid;
 
 /// <summary>
-/// Additional options (expiration, etc.) that apply to a <see cref="HybridCache"/> operation. When options
+/// Specifies additional options (for example, expiration) that apply to a <see cref="HybridCache"/> operation. When options
 /// can be specified at multiple levels (for example, globally and per-call), the values are composed; the
 /// most granular non-null value is used, with null values being inherited. If no value is specified at
-/// any level, the implementation may choose a reasonable default.
+/// any level, the implementation can choose a reasonable default.
 /// </summary>
 public sealed class HybridCacheEntryOptions
 {

src/libraries/Microsoft.Extensions.Caching.Abstractions/src/Hybrid/IHybridCacheSerializer.cs

@@ -6,18 +6,18 @@
 namespace Microsoft.Extensions.Caching.Hybrid;
 
 /// <summary>
-/// Per-type serialization/deserialization support for <see cref="HybridCache"/>.
+/// Provides per-type serialization and deserialization support for <see cref="HybridCache"/>.
 /// </summary>
 /// <typeparam name="T">The type being serialized/deserialized.</typeparam>
 public interface IHybridCacheSerializer<T>
 {
     /// <summary>
-    /// Deserialize a <typeparamref name="T"/> value from the provided <paramref name="source"/>.
+    /// Deserializes a <typeparamref name="T"/> value from the provided <paramref name="source"/>.
     /// </summary>
     T Deserialize(ReadOnlySequence<byte> source);
 
     /// <summary>
-    /// Serialize <paramref name="value"/> to the provided <paramref name="target"/>.
+    /// Serializes <paramref name="value"/> to the provided <paramref name="target"/>.
     /// </summary>
     void Serialize(T value, IBufferWriter<byte> target);
 }

src/libraries/Microsoft.Extensions.Caching.Abstractions/src/Hybrid/IHybridCacheSerializerFactory.cs

@@ -11,9 +11,9 @@ namespace Microsoft.Extensions.Caching.Hybrid;
 public interface IHybridCacheSerializerFactory
 {
     /// <summary>
-    /// Request a serializer for the provided type, if possible.
+    /// Requests a serializer for the provided type, if possible.
     /// </summary>
-    /// <typeparam name="T">The type being serialized/deserialized.</typeparam>
+    /// <typeparam name="T">The type being serialized or deserialized.</typeparam>
     /// <param name="serializer">The serializer.</param>
     /// <returns><c>true</c> if the factory supports this type, <c>false</c> otherwise.</returns>
     bool TryCreateSerializer<T>([NotNullWhen(true)] out IHybridCacheSerializer<T>? serializer);

src/libraries/Microsoft.Extensions.Caching.Abstractions/src/IBufferDistributedCache.cs

@@ -13,22 +13,22 @@
 public interface IBufferDistributedCache : IDistributedCache
 {
     /// <summary>
-    /// Attempt to retrieve an existing cache item.
+    /// Attempts to retrieve an existing cache item.
     /// </summary>
     /// <param name="key">The unique key for the cache item.</param>
     /// <param name="destination">The target to write the cache contents on success.</param>
     /// <returns><c>true</c> if the cache item is found, <c>false</c> otherwise.</returns>
-    /// <remarks>This is functionally similar to <see cref="IDistributedCache.Get(string)"/>, but avoids the array allocation.</remarks>
+    /// <remarks>This method is functionally similar to <see cref="IDistributedCache.Get(string)"/>, but avoids the array allocation.</remarks>
     bool TryGet(string key, IBufferWriter<byte> destination);
 
     /// <summary>
-    /// Asynchronously attempt to retrieve an existing cache entry.
+    /// Asynchronously attempts to retrieve an existing cache entry.
     /// </summary>
     /// <param name="key">The unique key for the cache entry.</param>
     /// <param name="destination">The target to write the cache contents on success.</param>
     /// <param name="token">The <see cref="CancellationToken"/> used to propagate notifications that the operation should be canceled.</param>
     /// <returns><c>true</c> if the cache entry is found, <c>false</c> otherwise.</returns>
-    /// <remarks>This is functionally similar to <see cref="IDistributedCache.GetAsync(string, CancellationToken)"/>, but avoids the array allocation.</remarks>
+    /// <remarks>This method is functionally similar to <see cref="IDistributedCache.GetAsync(string, CancellationToken)"/>, but avoids the array allocation.</remarks>
     ValueTask<bool> TryGetAsync(string key, IBufferWriter<byte> destination, CancellationToken token = default);
 
     /// <summary>
@@ -37,7 +37,7 @@ public interface IBufferDistributedCache : IDistributedCache
     /// <param name="key">The key of the entry to create.</param>
     /// <param name="value">The value for this cache entry.</param>
     /// <param name="options">The cache options for the entry.</param>
-    /// <remarks>This is functionally similar to <see cref="IDistributedCache.Set(string, byte[], DistributedCacheEntryOptions)"/>, but avoids the array allocation.</remarks>
+    /// <remarks>This method is functionally similar to <see cref="IDistributedCache.Set(string, byte[], DistributedCacheEntryOptions)"/>, but avoids the array allocation.</remarks>
     void Set(string key, ReadOnlySequence<byte> value, DistributedCacheEntryOptions options);
 
     /// <summary>
@@ -47,6 +47,6 @@ public interface IBufferDistributedCache : IDistributedCache
     /// <param name="value">The value for this cache entry.</param>
     /// <param name="options">The cache options for the value.</param>
     /// <param name="token">The <see cref="CancellationToken"/> used to propagate notifications that the operation should be canceled.</param>
-    /// <remarks>This is functionally similar to <see cref="IDistributedCache.SetAsync(string, byte[], DistributedCacheEntryOptions, CancellationToken)"/>, but avoids the array allocation.</remarks>
+    /// <remarks>This method is functionally similar to <see cref="IDistributedCache.SetAsync(string, byte[], DistributedCacheEntryOptions, CancellationToken)"/>, but avoids the array allocation.</remarks>
     ValueTask SetAsync(string key, ReadOnlySequence<byte> value, DistributedCacheEntryOptions options, CancellationToken token = default);
 }

src/libraries/Microsoft.Extensions.Caching.Abstractions/src/MemoryCacheEntryExtensions.cs

@@ -45,7 +45,7 @@ public static MemoryCacheEntryOptions SetSize(
         }
 
         /// <summary>
-        /// Expire the cache entry if the given <see cref="IChangeToken"/> expires.
+        /// Expires the cache entry if the given <see cref="IChangeToken"/> expires.
         /// </summary>
         /// <param name="options">The <see cref="MemoryCacheEntryOptions"/>.</param>
         /// <param name="expirationToken">The <see cref="IChangeToken"/> that causes the cache entry to expire.</param>
@@ -104,7 +104,7 @@ public static MemoryCacheEntryOptions SetSlidingExpiration(
         }
 
         /// <summary>
-        /// The given callback will be fired after the cache entry is evicted from the cache.
+        /// Fires the given callback after the cache entry is evicted from the cache.
         /// </summary>
         /// <param name="options">The <see cref="MemoryCacheEntryOptions"/>.</param>
         /// <param name="callback">The callback to register for calling after an entry is evicted.</param>
@@ -119,7 +119,7 @@ public static MemoryCacheEntryOptions RegisterPostEvictionCallback(
         }
 
         /// <summary>
-        /// The given callback will be fired after the cache entry is evicted from the cache.
+        /// Fires the given callback after the cache entry is evicted from the cache.
         /// </summary>
         /// <param name="options">The <see cref="MemoryCacheEntryOptions"/>.</param>
         /// <param name="callback">The callback to register for calling after an entry is evicted.</param>