Ensure OutputCaching generates a documentation file (#55170)

* Ensure OutputCaching generates a documentation file

Seems we aren't shipping any API docs for Output Caching 😢 

Ideally we'd backport this to 8.0.x but I'm not sure if the mechanics of servicing support it (ref assembly doc file change only).

* Naively fix doc comment warnings

* Remove unnecessary usings

---------

Co-authored-by: Andrew Casey <[email protected]>

Author: DamianEdwards

src/Middleware/OutputCaching/src/IOutputCacheBufferStore.cs

@@ -7,7 +7,7 @@
 namespace Microsoft.AspNetCore.OutputCaching;
 
 /// <summary>
-/// Represents a store for cached responses that uses a <see cref="IBufferWriter{byte}"/> as the target.
+/// Represents a store for cached responses that uses a <see cref="IBufferWriter{Byte}"/> as the target.
 /// </summary>
 public interface IOutputCacheBufferStore : IOutputCacheStore
 {

src/Middleware/OutputCaching/src/IOutputCachePolicy.cs

@@ -13,18 +13,22 @@ public interface IOutputCachePolicy
     /// At that point the cache middleware can still be enabled or disabled for the request.
     /// </summary>
     /// <param name="context">The current request's cache context.</param>
+    /// <param name="cancellation">The token to monitor for cancellation requests.</param>
     ValueTask CacheRequestAsync(OutputCacheContext context, CancellationToken cancellation);
 
     /// <summary>
     /// Updates the <see cref="OutputCacheContext"/> before the cached response is used.
     /// At that point the freshness of the cached response can be updated.
     /// </summary>
     /// <param name="context">The current request's cache context.</param>
+    /// <param name="cancellation">The token to monitor for cancellation requests.</param>
     ValueTask ServeFromCacheAsync(OutputCacheContext context, CancellationToken cancellation);
 
     /// <summary>
     /// Updates the <see cref="OutputCacheContext"/> before the response is served and can be cached.
     /// At that point cacheability of the response can be updated.
     /// </summary>
+    /// <param name="context">The current request's cache context.</param>
+    /// <param name="cancellation">The token to monitor for cancellation requests.</param>
     ValueTask ServeResponseAsync(OutputCacheContext context, CancellationToken cancellation);
 }

src/Middleware/OutputCaching/src/Microsoft.AspNetCore.OutputCaching.csproj

@@ -3,6 +3,7 @@
   <PropertyGroup>
     <Description>ASP.NET Core middleware for caching HTTP responses on the server.</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
     <IsPackable>false</IsPackable>
     <IsTrimmable>true</IsTrimmable>

src/Middleware/OutputCaching/src/OutputCacheContext.cs

@@ -10,6 +10,9 @@ namespace Microsoft.AspNetCore.OutputCaching;
 /// </summary>
 public sealed class OutputCacheContext
 {
+    /// <summary>
+    /// Constructs a new instance of <see cref="OutputCacheContext"/>.
+    /// </summary>
     public OutputCacheContext()
     {
     }

src/Middleware/OutputCaching/src/OutputCacheEntryFormatter.cs

@@ -5,8 +5,6 @@
 using System.Collections.Frozen;
 using System.Diagnostics;
 using System.Linq;
-using System.Runtime.CompilerServices;
-using System.Text;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Primitives;
 using Microsoft.Net.Http.Headers;

src/Middleware/OutputCaching/src/OutputCachePolicyBuilder.cs

@@ -117,7 +117,8 @@ public OutputCachePolicyBuilder SetVaryByQuery(string[] queryKeys)
     /// <summary>
     /// Adds a policy to vary the cached responses by header.
     /// </summary>
-    /// <param name="headerNames">The header names to vary the cached responses by.</param>
+    /// <param name="headerName">The header name to vary the cached responses by.</param>
+    /// <param name="headerNames">Additional header names to vary the cached responses by.</param>
     public OutputCachePolicyBuilder SetVaryByHeader(string headerName, params string[] headerNames)
     {
         ArgumentNullException.ThrowIfNull(headerName);
@@ -269,7 +270,7 @@ public OutputCachePolicyBuilder Expire(TimeSpan expiration)
     /// <summary>
     /// Adds a policy to change the request locking strategy.
     /// </summary>
-    /// <param name="lockResponse">Whether the request should be locked.</param>
+    /// <param name="enabled">Whether the request should be locked.</param>
     /// <remarks>When the default policy is used, locking is enabled by default.</remarks>
     public OutputCachePolicyBuilder SetLocking(bool enabled) => AddPolicy(enabled ? LockingPolicy.Enabled : LockingPolicy.Disabled);
 

src/Middleware/OutputCaching/src/Policies/OutputCacheConventionBuilderExtensions.cs

@@ -46,6 +46,7 @@ public static TBuilder CacheOutput<TBuilder>(this TBuilder builder, IOutputCache
     /// <summary>
     /// Marks an endpoint to be cached using the specified policy builder.
     /// </summary>
+    /// <param name="builder">The <see cref="IEndpointConventionBuilder"/>.</param>
     /// <param name="policy">An action on <see cref="OutputCachePolicyBuilder"/>.</param>
     public static TBuilder CacheOutput<TBuilder>(this TBuilder builder, Action<OutputCachePolicyBuilder> policy)
         where TBuilder : IEndpointConventionBuilder
@@ -54,6 +55,7 @@ public static TBuilder CacheOutput<TBuilder>(this TBuilder builder, Action<Outpu
     /// <summary>
     /// Marks an endpoint to be cached using the specified policy builder.
     /// </summary>
+    /// <param name="builder">The <see cref="IEndpointConventionBuilder"/>.</param>
     /// <param name="policy">An action on <see cref="OutputCachePolicyBuilder"/>.</param>
     /// <param name="excludeDefaultPolicy">Whether to exclude the default policy or not.</param>
     public static TBuilder CacheOutput<TBuilder>(this TBuilder builder, Action<OutputCachePolicyBuilder> policy, bool excludeDefaultPolicy) where TBuilder : IEndpointConventionBuilder