Add API docs for Caching and WebEncoders (#28945)

* Add API docs for Caching and WebEncoders

Co-authored-by: Pranav K <[email protected]>

src/Caching/SqlServer/src/Microsoft.Extensions.Caching.SqlServer.csproj

@@ -3,7 +3,6 @@
   <PropertyGroup>
     <Description>Distributed cache implementation of Microsoft.Extensions.Caching.Distributed.IDistributedCache using Microsoft SQL Server.</Description>
     <TargetFramework>netstandard2.0</TargetFramework>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>cache;distributedcache;sqlserver</PackageTags>
     <ExcludeFromSourceBuild>true</ExcludeFromSourceBuild>

src/Caching/SqlServer/src/SqlServerCache.cs

@@ -27,6 +27,10 @@ namespace Microsoft.Extensions.Caching.SqlServer
         private readonly TimeSpan _defaultSlidingExpiration;
         private readonly Object _mutex = new Object();
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="SqlServerCache"/>.
+        /// </summary>
+        /// <param name="options">The configuration options.</param>
         public SqlServerCache(IOptions<SqlServerCacheOptions> options)
         {
             var cacheOptions = options.Value;
@@ -88,6 +92,7 @@ namespace Microsoft.Extensions.Caching.SqlServer
             }
         }
 
+        /// <inheritdoc />
         public byte[] Get(string key)
         {
             if (key == null)
@@ -102,6 +107,7 @@ namespace Microsoft.Extensions.Caching.SqlServer
             return value;
         }
 
+        /// <inheritdoc />
         public async Task<byte[]> GetAsync(string key, CancellationToken token = default(CancellationToken))
         {
             if (key == null)
@@ -118,6 +124,7 @@ namespace Microsoft.Extensions.Caching.SqlServer
             return value;
         }
 
+        /// <inheritdoc />
         public void Refresh(string key)
         {
             if (key == null)
@@ -130,6 +137,7 @@ namespace Microsoft.Extensions.Caching.SqlServer
             ScanForExpiredItemsIfRequired();
         }
 
+        /// <inheritdoc />
         public async Task RefreshAsync(string key, CancellationToken token = default(CancellationToken))
         {
             if (key == null)
@@ -144,6 +152,7 @@ namespace Microsoft.Extensions.Caching.SqlServer
             ScanForExpiredItemsIfRequired();
         }
 
+        /// <inheritdoc />
         public void Remove(string key)
         {
             if (key == null)
@@ -156,6 +165,7 @@ namespace Microsoft.Extensions.Caching.SqlServer
             ScanForExpiredItemsIfRequired();
         }
 
+        /// <inheritdoc />
         public async Task RemoveAsync(string key, CancellationToken token = default(CancellationToken))
         {
             if (key == null)
@@ -170,6 +180,7 @@ namespace Microsoft.Extensions.Caching.SqlServer
             ScanForExpiredItemsIfRequired();
         }
 
+        /// <inheritdoc />
         public void Set(string key, byte[] value, DistributedCacheEntryOptions options)
         {
             if (key == null)
@@ -194,6 +205,7 @@ namespace Microsoft.Extensions.Caching.SqlServer
             ScanForExpiredItemsIfRequired();
         }
 
+        /// <inheritdoc />
         public async Task SetAsync(
             string key,
             byte[] value,

src/Caching/StackExchangeRedis/src/Microsoft.Extensions.Caching.StackExchangeRedis.csproj

@@ -1,9 +1,8 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>Distributed cache implementation of Microsoft.Extensions.Caching.Distributed.IDistributedCache using Redis.</Description>
     <TargetFramework>netstandard2.0</TargetFramework>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>cache;distributedcache;redis</PackageTags>
     <ExcludeFromSourceBuild>true</ExcludeFromSourceBuild>

src/Caching/StackExchangeRedis/src/RedisCache.cs

@@ -11,6 +11,10 @@ using StackExchange.Redis;
 
 namespace Microsoft.Extensions.Caching.StackExchangeRedis
 {
+    /// <summary>
+    /// Distributed cache implementation using Redis.
+    /// <para>Uses <c>StackExchange.Redis</c> as the Redis client.</para>
+    /// </summary>
     public class RedisCache : IDistributedCache, IDisposable
     {
         // KEYS[1] = = key
@@ -39,6 +43,10 @@ namespace Microsoft.Extensions.Caching.StackExchangeRedis
 
         private readonly SemaphoreSlim _connectionLock = new SemaphoreSlim(initialCount: 1, maxCount: 1);
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="RedisCache"/>.
+        /// </summary>
+        /// <param name="optionsAccessor">The configuration options.</param>
         public RedisCache(IOptions<RedisCacheOptions> optionsAccessor)
         {
             if (optionsAccessor == null)
@@ -52,6 +60,7 @@ namespace Microsoft.Extensions.Caching.StackExchangeRedis
             _instance = _options.InstanceName ?? string.Empty;
         }
 
+        /// <inheritdoc />
         public byte[] Get(string key)
         {
             if (key == null)
@@ -62,6 +71,7 @@ namespace Microsoft.Extensions.Caching.StackExchangeRedis
             return GetAndRefresh(key, getData: true);
         }
 
+        /// <inheritdoc />
         public async Task<byte[]> GetAsync(string key, CancellationToken token = default(CancellationToken))
         {
             if (key == null)
@@ -74,6 +84,7 @@ namespace Microsoft.Extensions.Caching.StackExchangeRedis
             return await GetAndRefreshAsync(key, getData: true, token: token).ConfigureAwait(false);
         }
 
+        /// <inheritdoc />
         public void Set(string key, byte[] value, DistributedCacheEntryOptions options)
         {
             if (key == null)
@@ -107,6 +118,7 @@ namespace Microsoft.Extensions.Caching.StackExchangeRedis
                 });
         }
 
+        /// <inheritdoc />
         public async Task SetAsync(string key, byte[] value, DistributedCacheEntryOptions options, CancellationToken token = default(CancellationToken))
         {
             if (key == null)
@@ -142,6 +154,7 @@ namespace Microsoft.Extensions.Caching.StackExchangeRedis
                 }).ConfigureAwait(false);
         }
 
+        /// <inheritdoc />
         public void Refresh(string key)
         {
             if (key == null)
@@ -152,6 +165,7 @@ namespace Microsoft.Extensions.Caching.StackExchangeRedis
             GetAndRefresh(key, getData: false);
         }
 
+        /// <inheritdoc />
         public async Task RefreshAsync(string key, CancellationToken token = default(CancellationToken))
         {
             if (key == null)
@@ -301,6 +315,7 @@ namespace Microsoft.Extensions.Caching.StackExchangeRedis
             return null;
         }
 
+        /// <inheritdoc />
         public void Remove(string key)
         {
             if (key == null)
@@ -314,6 +329,7 @@ namespace Microsoft.Extensions.Caching.StackExchangeRedis
             // TODO: Error handling
         }
 
+        /// <inheritdoc />
         public async Task RemoveAsync(string key, CancellationToken token = default(CancellationToken))
         {
             if (key == null)
@@ -432,6 +448,7 @@ namespace Microsoft.Extensions.Caching.StackExchangeRedis
             return options.AbsoluteExpiration;
         }
 
+        /// <inheritdoc />
         public void Dispose()
         {
             if (_disposed)

src/WebEncoders/src/Microsoft.Extensions.WebEncoders.csproj

@@ -4,7 +4,6 @@
     <Description>Contains registration and configuration APIs to add the core framework encoders to a dependency injection container.</Description>
     <TargetFrameworks>$(DefaultNetFxTargetFramework);netstandard2.0;$(DefaultNetCoreTargetFramework)</TargetFrameworks>
     <TargetFrameworks Condition="'$(DotNetBuildFromSource)' == 'true'">$(DefaultNetCoreTargetFramework)</TargetFrameworks>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore</PackageTags>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>

src/WebEncoders/src/Testing/HtmlTestEncoder.cs

@@ -8,15 +8,17 @@ using System.Text.Encodings.Web;
 namespace Microsoft.Extensions.WebEncoders.Testing
 {
     /// <summary>
-    /// Encoder used for unit testing.
+    /// <see cref="HtmlEncoder"/> used for unit testing. This encoder does not perform any encoding and should not be used in application code.
     /// </summary>
     public sealed class HtmlTestEncoder : HtmlEncoder
     {
+        /// <inheritdoc />
         public override int MaxOutputCharactersPerInputCharacter
         {
             get { return 1; }
         }
 
+        /// <inheritdoc />
         public override string Encode(string value)
         {
             if (value == null)
@@ -32,6 +34,7 @@ namespace Microsoft.Extensions.WebEncoders.Testing
             return $"HtmlEncode[[{value}]]";
         }
 
+        /// <inheritdoc />
         public override void Encode(TextWriter output, char[] value, int startIndex, int characterCount)
         {
             if (output == null)
@@ -54,6 +57,7 @@ namespace Microsoft.Extensions.WebEncoders.Testing
             output.Write("]]");
         }
 
+        /// <inheritdoc />
         public override void Encode(TextWriter output, string value, int startIndex, int characterCount)
         {
             if (output == null)
@@ -76,16 +80,19 @@ namespace Microsoft.Extensions.WebEncoders.Testing
             output.Write("]]");
         }
 
+        /// <inheritdoc />
         public override bool WillEncode(int unicodeScalar)
         {
             return false;
         }
 
+        /// <inheritdoc />
         public override unsafe int FindFirstCharacterToEncode(char* text, int textLength)
         {
             return -1;
         }
 
+        /// <inheritdoc />
         public override unsafe bool TryEncodeUnicodeScalar(
             int unicodeScalar,
             char* buffer,
@@ -101,4 +108,4 @@ namespace Microsoft.Extensions.WebEncoders.Testing
             return false;
         }
     }
-}
+}

src/WebEncoders/src/Testing/JavaScriptTestEncoder.cs

@@ -8,15 +8,17 @@ using System.Text.Encodings.Web;
 namespace Microsoft.Extensions.WebEncoders.Testing
 {
     /// <summary>
-    /// Encoder used for unit testing.
+    /// <see cref="JavaScriptEncoder"/> used for unit testing. This encoder does not perform any encoding and should not be used in application code.
     /// </summary>
     public class JavaScriptTestEncoder : JavaScriptEncoder
     {
+        /// <inheritdoc />
         public override int MaxOutputCharactersPerInputCharacter
         {
             get { return 1; }
         }
 
+        /// <inheritdoc />
         public override string Encode(string value)
         {
             if (value == null)
@@ -32,6 +34,7 @@ namespace Microsoft.Extensions.WebEncoders.Testing
             return $"JavaScriptEncode[[{value}]]";
         }
 
+        /// <inheritdoc />
         public override void Encode(TextWriter output, char[] value, int startIndex, int characterCount)
         {
             if (output == null)
@@ -54,6 +57,7 @@ namespace Microsoft.Extensions.WebEncoders.Testing
             output.Write("]]");
         }
 
+        /// <inheritdoc />
         public override void Encode(TextWriter output, string value, int startIndex, int characterCount)
         {
             if (output == null)
@@ -76,16 +80,19 @@ namespace Microsoft.Extensions.WebEncoders.Testing
             output.Write("]]");
         }
 
+        /// <inheritdoc />
         public override bool WillEncode(int unicodeScalar)
         {
             return false;
         }
 
+        /// <inheritdoc />
         public override unsafe int FindFirstCharacterToEncode(char* text, int textLength)
         {
             return -1;
         }
 
+        /// <inheritdoc />
         public override unsafe bool TryEncodeUnicodeScalar(
             int unicodeScalar,
             char* buffer,
@@ -101,4 +108,4 @@ namespace Microsoft.Extensions.WebEncoders.Testing
             return false;
         }
     }
-}
+}

src/WebEncoders/src/Testing/UrlTestEncoder.cs

@@ -8,15 +8,17 @@ using System.Text.Encodings.Web;
 namespace Microsoft.Extensions.WebEncoders.Testing
 {
     /// <summary>
-    /// Encoder used for unit testing.
+    /// <see cref="UrlEncoder"/> used for unit testing. This encoder does not perform any encoding and should not be used in application code.
     /// </summary>
     public class UrlTestEncoder : UrlEncoder
     {
+        /// <inheritdoc />
         public override int MaxOutputCharactersPerInputCharacter
         {
             get { return 1; }
         }
 
+        /// <inheritdoc />
         public override string Encode(string value)
         {
             if (value == null)
@@ -32,6 +34,7 @@ namespace Microsoft.Extensions.WebEncoders.Testing
             return $"UrlEncode[[{value}]]";
         }
 
+        /// <inheritdoc />
         public override void Encode(TextWriter output, char[] value, int startIndex, int characterCount)
         {
             if (output == null)
@@ -54,6 +57,7 @@ namespace Microsoft.Extensions.WebEncoders.Testing
             output.Write("]]");
         }
 
+        /// <inheritdoc />
         public override void Encode(TextWriter output, string value, int startIndex, int characterCount)
         {
             if (output == null)
@@ -76,16 +80,19 @@ namespace Microsoft.Extensions.WebEncoders.Testing
             output.Write("]]");
         }
 
+        /// <inheritdoc />
         public override bool WillEncode(int unicodeScalar)
         {
             return false;
         }
 
+        /// <inheritdoc />
         public override unsafe int FindFirstCharacterToEncode(char* text, int textLength)
         {
             return -1;
         }
 
+        /// <inheritdoc />
         public override unsafe bool TryEncodeUnicodeScalar(
             int unicodeScalar,
             char* buffer,
@@ -101,4 +108,4 @@ namespace Microsoft.Extensions.WebEncoders.Testing
             return false;
         }
     }
-}
+}