Add docs to CookiePolicy (#26446)

* Add docs to CookiePolicy

Contributes to https://github.com/dotnet/aspnetcore/issues/26397

* Apply suggestions from code review

src/Security/CookiePolicy/src/AppendCookieContext.cs

@@ -1,12 +1,23 @@
 // Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
+using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.CookiePolicy
 {
+    /// <summary>
+    /// Context for <see cref="CookiePolicyOptions.OnAppendCookie"/> that allows changes to the cookie prior to being appended.
+    /// </summary>
     public class AppendCookieContext
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="AppendCookieContext"/>.
+        /// </summary>
+        /// <param name="context">The request <see cref="HttpContext"/>.</param>
+        /// <param name="options">The <see cref="Http.CookieOptions"/> passed to the cookie policy.</param>
+        /// <param name="name">The cookie name.</param>
+        /// <param name="value">The cookie value.</param>
         public AppendCookieContext(HttpContext context, CookieOptions options, string name, string value)
         {
             Context = context;
@@ -15,12 +26,40 @@ namespace Microsoft.AspNetCore.CookiePolicy
             CookieValue = value;
         }
 
+        /// <summary>
+        /// Gets the <see cref="HttpContext"/>.
+        /// </summary>
         public HttpContext Context { get; }
+
+        /// <summary>
+        /// Gets the <see cref="Http.CookieOptions"/>.
+        /// </summary>
         public CookieOptions CookieOptions { get; }
+
+        /// <summary>
+        /// Gets or sets the cookie name.
+        /// </summary>
         public string CookieName { get; set; }
+
+        /// <summary>
+        /// Gets or sets the cookie value.
+        /// </summary>
         public string CookieValue { get; set; }
+
+        /// <summary>
+        /// Gets a value that determines if cookie consent is required before setting this cookie.
+        /// </summary>
         public bool IsConsentNeeded { get; internal set; }
+
+        /// <summary>
+        /// Gets a value that determines if cookie consent was provided.
+        /// </summary>
         public bool HasConsent { get; internal set; }
+
+        /// <summary>
+        /// Gets or sets a value that determines if the cookie can be appended. If set to <see langword="false" />,
+        /// the cookie is not appended.
+        /// </summary>
         public bool IssueCookie { get; set; }
     }
-}
+}

src/Security/CookiePolicy/src/CookiePolicyMiddleware.cs

@@ -12,11 +12,20 @@ using Microsoft.Extensions.Options;
 
 namespace Microsoft.AspNetCore.CookiePolicy
 {
+    /// <summary>
+    /// Initializes a new instance of <see cref="CookiePolicyMiddleware"/>.
+    /// </summary>
     public class CookiePolicyMiddleware
     {
         private readonly RequestDelegate _next;
         private readonly ILogger _logger;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="CookiePolicyMiddleware"/>.
+        /// </summary>
+        /// <param name="next">A reference to the next item in the application pipeline.</param>
+        /// <param name="options">Accessor to <see cref="CookiePolicyOptions"/>.</param>
+        /// <param name="factory">The <see cref="ILoggerFactory"/>.</param>
         public CookiePolicyMiddleware(RequestDelegate next, IOptions<CookiePolicyOptions> options, ILoggerFactory factory)
         {
             Options = options.Value;
@@ -24,6 +33,11 @@ namespace Microsoft.AspNetCore.CookiePolicy
             _logger = factory.CreateLogger<CookiePolicyMiddleware>();
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="CookiePolicyMiddleware"/>.
+        /// </summary>
+        /// <param name="next">A reference to the next item in the application pipeline.</param>
+        /// <param name="options">Accessor to <see cref="CookiePolicyOptions"/>.</param>
         public CookiePolicyMiddleware(RequestDelegate next, IOptions<CookiePolicyOptions> options)
         {
             Options = options.Value;
@@ -31,8 +45,15 @@ namespace Microsoft.AspNetCore.CookiePolicy
             _logger = NullLogger.Instance;
         }
 
+        /// <summary>
+        /// Gets or sets the <see cref="CookiePolicyOptions"/>.
+        /// </summary>
         public CookiePolicyOptions Options { get; set; }
 
+        /// <summary>
+        /// Invokes the middleware.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext" />.</param>
         public Task Invoke(HttpContext context)
         {
             var feature = context.Features.Get<IResponseCookiesFeature>() ?? new ResponseCookiesFeature(context.Features);
@@ -53,4 +74,4 @@ namespace Microsoft.AspNetCore.CookiePolicy
             public IResponseCookies Cookies { get; }
         }
     }
-}
+}

src/Security/CookiePolicy/src/CookiePolicyOptions.cs

@@ -27,6 +27,10 @@ namespace Microsoft.AspNetCore.Builder
         /// </summary>
         public CookieSecurePolicy Secure { get; set; } = CookieSecurePolicy.None;
 
+        /// <summary>
+        /// Gets or sets the <see cref="CookieBuilder"/> that is used to track if the user consented to the
+        /// cookie use policy.
+        /// </summary>
         public CookieBuilder ConsentCookie { get; set; } = new CookieBuilder()
         {
             Name = ".AspNet.Consent",

src/Security/CookiePolicy/src/DeleteCookieContext.cs

@@ -1,12 +1,22 @@
 // Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
+using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.CookiePolicy
 {
+    /// <summary>
+    /// Context for <see cref="CookiePolicyOptions.OnDeleteCookie"/> that allows changes to the cookie prior to being deleted.
+    /// </summary>
     public class DeleteCookieContext
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="DeleteCookieContext"/>.
+        /// </summary>
+        /// <param name="context">The request <see cref="HttpContext"/>.</param>
+        /// <param name="options">The <see cref="Http.CookieOptions"/> passed to the cookie policy.</param>
+        /// <param name="name">The cookie name to be deleted.</param>
         public DeleteCookieContext(HttpContext context, CookieOptions options, string name)
         {
             Context = context;
@@ -14,11 +24,35 @@ namespace Microsoft.AspNetCore.CookiePolicy
             CookieName = name;
         }
 
+        /// <summary>
+        /// Gets the <see cref="HttpContext"/>.
+        /// </summary>
         public HttpContext Context { get; }
+
+        /// <summary>
+        /// Gets the <see cref="Http.CookieOptions"/>.
+        /// </summary>
         public CookieOptions CookieOptions { get; }
+
+        /// <summary>
+        /// Gets or sets the cookie name.
+        /// </summary>
         public string CookieName { get; set; }
+
+        /// <summary>
+        /// Gets a value that determines if cookie consent is required before setting this cookie.
+        /// </summary>
         public bool IsConsentNeeded { get; internal set; }
+
+        /// <summary>
+        /// Gets a value that determines if cookie consent was provided.
+        /// </summary>
         public bool HasConsent { get; internal set; }
+
+        /// <summary>
+        /// Gets or sets a value that determines if the cookie can be deleted. If set to <see langword="false" />,
+        /// cookie deletion is suppressed.
+        /// </summary>
         public bool IssueCookie { get; set; }
     }
-}
+}

src/Security/CookiePolicy/src/HttpOnlyPolicy.cs

@@ -3,9 +3,21 @@
 
 namespace Microsoft.AspNetCore.CookiePolicy
 {
+    /// <summary>
+    /// Describes the HttpOnly behavior for cookies.
+    /// </summary>
     public enum HttpOnlyPolicy
     {
+        /// <summary>
+        /// The cookie does not have a configured HttpOnly behavior. This cookie can be accessed by
+        /// JavaScript <c>document.cookie</c> API.
+        /// </summary>
         None,
+
+        /// <summary>
+        /// The cookie is configured with a HttpOnly attribute. This cookie inaccessible to the
+        /// JavaScript <c>document.cookie</c> API.
+        /// </summary>
         Always
     }
-}
+}

src/Security/CookiePolicy/src/Microsoft.AspNetCore.CookiePolicy.csproj

@@ -1,10 +1,10 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>ASP.NET Core cookie policy classes to control the behavior of cookies.</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore</PackageTags>
     <IsPackable>false</IsPackable>