Dairai/add http class descriptions (#17349)

Author: analogrelay

src/Http/Http.Abstractions/src/HttpMethods.cs

@@ -5,12 +5,15 @@
 
 namespace Microsoft.AspNetCore.Http
 {
+    /// <summary>
+    /// Contains methods to verify the request method of an HTTP request. 
+    /// </summary>
     public static class HttpMethods
     {
         // We are intentionally using 'static readonly' here instead of 'const'.
-        // 'const' values would be embedded in to each assembly that used them
+        // 'const' values would be embedded into each assembly that used them
         // and each consuming assembly would have a different 'string' instance.
-        // Using .'static readonly' means that all consumers get thee exact same
+        // Using .'static readonly' means that all consumers get these exact same
         // 'string' instance, which means the 'ReferenceEquals' checks below work
         // and allow us to optimize comparisons when these constants are used.
 
@@ -25,46 +28,109 @@ public static class HttpMethods
         public static readonly string Put = "PUT";
         public static readonly string Trace = "TRACE";
 
+        /// <summary>
+        /// Returns a value that indicates if the HTTP request method is CONNECT. 
+        /// </summary>
+        /// <param name="method">The HTTP request method.</param>
+        /// <returns>
+        /// <see langword="true" /> if the method is CONNECT; otherwise, <see langword="false" />.
+        /// </returns>
         public static bool IsConnect(string method)
         {
             return object.ReferenceEquals(Connect, method) || StringComparer.OrdinalIgnoreCase.Equals(Connect, method);
         }
 
+        /// <summary>
+        /// Returns a value that indicates if the HTTP request method is DELETE. 
+        /// </summary>
+        /// <param name="method">The HTTP request method.</param>
+        /// <returns>
+        /// <see langword="true" /> if the method is DELETE; otherwise, <see langword="false" />.
+        /// </returns>
         public static bool IsDelete(string method)
         {
             return object.ReferenceEquals(Delete, method) || StringComparer.OrdinalIgnoreCase.Equals(Delete, method);
         }
 
+        /// <summary>
+        /// Returns a value that indicates if the HTTP request method is GET. 
+        /// </summary>
+        /// <param name="method">The  HTTP request method.</param>
+        /// <returns>
+         /// <see langword="true" /> if the method is GET; otherwise, <see langword="false" />.
+        /// </returns>
         public static bool IsGet(string method)
         {
             return object.ReferenceEquals(Get, method) || StringComparer.OrdinalIgnoreCase.Equals(Get, method);
         }
 
+        /// <summary>
+        /// Returns a value that indicates if the HTTP request method is HEAD. 
+        /// </summary>
+        /// <param name="method">The HTTP request method.</param>
+        /// <returns>
+         /// <see langword="true" /> if the method is HEAD; otherwise, <see langword="false" />.
+        /// </returns>
         public static bool IsHead(string method)
         {
             return object.ReferenceEquals(Head, method) || StringComparer.OrdinalIgnoreCase.Equals(Head, method);
         }
 
+        /// <summary>
+        /// Returns a value that indicates if the HTTP request method is OPTIONS. 
+        /// </summary>
+        /// <param name="method">The HTTP request method.</param>
+        /// <returns>
+         /// <see langword="true" /> if the method is OPTIONS; otherwise, <see langword="false" />.
+        /// </returns>
         public static bool IsOptions(string method)
         {
             return object.ReferenceEquals(Options, method) || StringComparer.OrdinalIgnoreCase.Equals(Options, method);
         }
 
+        /// <summary>
+        /// Returns a value that indicates if the HTTP request method is PATCH. 
+        /// </summary>
+        /// <param name="method">The HTTP request method.</param>
+        /// <returns>
+        /// <see langword="true" /> if the method is PATCH; otherwise, <see langword="false" />.
+        /// </returns>
         public static bool IsPatch(string method)
         {
             return object.ReferenceEquals(Patch, method) || StringComparer.OrdinalIgnoreCase.Equals(Patch, method);
         }
 
+        /// <summary>
+        /// Returns a value that indicates if the HTTP request method is POST. 
+        /// </summary>
+        /// <param name="method">The HTTP request method.</param>
+        /// <returns>
+        /// <see langword="true" /> if the method is POST; otherwise, <see langword="false" />.
+        /// </returns>
         public static bool IsPost(string method)
         {
             return object.ReferenceEquals(Post, method) || StringComparer.OrdinalIgnoreCase.Equals(Post, method);
         }
 
+        /// <summary>
+        /// Returns a value that indicates if the HTTP request method is PUT. 
+        /// </summary>
+        /// <param name="method">The HTTP request method.</param>
+        /// <returns>
+        /// <see langword="true" /> if the method is PUT; otherwise, <see langword="false" />.
+        /// </returns>
         public static bool IsPut(string method)
         {
             return object.ReferenceEquals(Put, method) || StringComparer.OrdinalIgnoreCase.Equals(Put, method);
         }
 
+        /// <summary>
+        /// Returns a value that indicates if the HTTP request method is TRACE. 
+        /// </summary>
+        /// <param name="method">The HTTP request method.</param>
+        /// <returns>
+        /// <see langword="true" /> if the method is TRACE; otherwise, <see langword="false" />.
+        /// </returns>
         public static bool IsTrace(string method)
         {
             return object.ReferenceEquals(Trace, method) || StringComparer.OrdinalIgnoreCase.Equals(Trace, method);

src/Http/Http/src/DefaultHttpContext.cs

@@ -13,6 +13,9 @@
 
 namespace Microsoft.AspNetCore.Http
 {
+    /// <summary>
+    /// Represents an implementation of the HTTP Context class. 
+    /// </summary>
     public sealed class DefaultHttpContext : HttpContext
     {
         // Lambdas hoisted to static readonly fields to improve inlining https://github.com/dotnet/roslyn/issues/13624
@@ -32,6 +35,9 @@ public sealed class DefaultHttpContext : HttpContext
         private DefaultConnectionInfo _connection;
         private DefaultWebSocketManager _websockets;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DefaultHttpContext"/> class.
+        /// </summary>
         public DefaultHttpContext()
             : this(new FeatureCollection())
         {
@@ -40,13 +46,24 @@ public DefaultHttpContext()
             Features.Set<IHttpResponseBodyFeature>(new StreamResponseBodyFeature(Stream.Null));
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DefaultHttpContext"/> class with provided features.
+        /// </summary>
+        /// <param name="features">Initial set of features for the <see cref="DefaultHttpContext"/>.</param>
         public DefaultHttpContext(IFeatureCollection features)
         {
             _features.Initalize(features);
             _request = new DefaultHttpRequest(this);
             _response = new DefaultHttpResponse(this);
         }
 
+        /// <summary>
+        /// Reinitialize  the current instant of the class with features passed in.
+        /// </summary>
+        /// <remarks>
+        /// This method allows the consumer to re-use the <see cref="DefaultHttpContext" /> for another request, rather than having to allocate a new instance.
+        /// </remarks>
+        /// <param name="features">The new set of features for the <see cref="DefaultHttpContext" />.</param>
         public void Initialize(IFeatureCollection features)
         {
             var revision = features.Revision;
@@ -57,6 +74,9 @@ public void Initialize(IFeatureCollection features)
             _websockets?.Initialize(features, revision);
         }
 
+        /// <summary>
+        /// Uninitialize all the features in the <see cref="DefaultHttpContext" />.
+        /// </summary>
         public void Uninitialize()
         {
             _features = default;
@@ -66,8 +86,20 @@ public void Uninitialize()
             _websockets?.Uninitialize();
         }
 
+        /// <summary>
+        /// Gets or set the <see cref="FormOptions" /> for this instance.
+        /// </summary>
+        /// <returns>
+        /// <see cref="FormOptions"/>        
+        /// </returns>
         public FormOptions FormOptions { get; set; }
 
+        /// <summary>
+        /// Gets or sets the <see cref="IServiceScopeFactory" /> for this instance.
+        /// </summary>
+        /// <returns>   
+        /// <see cref="IServiceScopeFactory"/>      
+        /// </returns>
         public IServiceScopeFactory ServiceScopeFactory { get; set; }
 
         private IItemsFeature ItemsFeature =>
@@ -92,16 +124,22 @@ public void Uninitialize()
         private IHttpRequestIdentifierFeature RequestIdentifierFeature =>
             _features.Fetch(ref _features.Cache.RequestIdentifier, _newHttpRequestIdentifierFeature);
 
+        /// <inheritdoc/>
         public override IFeatureCollection Features => _features.Collection ?? ContextDisposed();
 
+        /// <inheritdoc/>
         public override HttpRequest Request => _request;
 
+        /// <inheritdoc/>
         public override HttpResponse Response => _response;
 
+        /// <inheritdoc/>
         public override ConnectionInfo Connection => _connection ?? (_connection = new DefaultConnectionInfo(Features));
 
+        /// <inheritdoc/>
         public override WebSocketManager WebSockets => _websockets ?? (_websockets = new DefaultWebSocketManager(Features));
 
+        /// <inheritdoc/>
         public override ClaimsPrincipal User
         {
             get
@@ -117,30 +155,35 @@ public override ClaimsPrincipal User
             set { HttpAuthenticationFeature.User = value; }
         }
 
+        /// <inheritdoc/>
         public override IDictionary<object, object> Items
         {
             get { return ItemsFeature.Items; }
             set { ItemsFeature.Items = value; }
         }
 
+        /// <inheritdoc/>
         public override IServiceProvider RequestServices
         {
             get { return ServiceProvidersFeature.RequestServices; }
             set { ServiceProvidersFeature.RequestServices = value; }
         }
 
+        /// <inheritdoc/>
         public override CancellationToken RequestAborted
         {
             get { return LifetimeFeature.RequestAborted; }
             set { LifetimeFeature.RequestAborted = value; }
         }
 
+        /// <inheritdoc/>
         public override string TraceIdentifier
         {
             get { return RequestIdentifierFeature.TraceIdentifier; }
             set { RequestIdentifierFeature.TraceIdentifier = value; }
         }
 
+        /// <inheritdoc/>
         public override ISession Session
         {
             get
@@ -166,6 +209,7 @@ public override ISession Session
         [EditorBrowsable(EditorBrowsableState.Never)]
         public HttpContext HttpContext => this;
 
+        /// <inheritdoc/>
         public override void Abort()
         {
             LifetimeFeature.Abort();

src/Http/Http/src/HttpContextAccessor.cs

@@ -5,10 +5,14 @@
 
 namespace Microsoft.AspNetCore.Http
 {
+    /// <summary>
+    /// Provides an implementation of <see cref="IHttpContextAccessor" /> based on the current execution context. 
+    /// </summary>
     public class HttpContextAccessor : IHttpContextAccessor
     {
         private static AsyncLocal<HttpContextHolder> _httpContextCurrent = new AsyncLocal<HttpContextHolder>();
 
+        /// <inheritdoc/>
         public HttpContext HttpContext
         {
             get

src/Http/Http/src/HttpContextFactory.cs

@@ -8,28 +8,51 @@
 
 namespace Microsoft.AspNetCore.Http
 {
+    /// <summary>
+    /// Represents methods used to create an HTTP context object. 
+    /// </summary>
     [Obsolete("This is obsolete and will be removed in a future version. Use DefaultHttpContextFactory instead.")]
     public class HttpContextFactory : IHttpContextFactory
     {
         private readonly IHttpContextAccessor _httpContextAccessor;
         private readonly FormOptions _formOptions;
         private readonly IServiceScopeFactory _serviceScopeFactory;
 
+        /// <summary>
+        /// Initializes a new instance of the HttpContext class with options passed in.
+        /// </summary>
+        /// <param name="formOptions">Options to set when instantianting the HTTP context object.</param>
         public HttpContextFactory(IOptions<FormOptions> formOptions)
             : this(formOptions, serviceScopeFactory: null)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the DefaultHttpContext class with options passed in.
+        /// </summary>
+        /// <param name="formOptions">Options to set when instantianting the HTTP context object.</param>
+        /// <param name="serviceScopeFactory">Factory object used to create the service scope for the HTTP context.</param>
         public HttpContextFactory(IOptions<FormOptions> formOptions, IServiceScopeFactory serviceScopeFactory)
             : this(formOptions, serviceScopeFactory, httpContextAccessor: null)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the DefaultHttpContext class with options passed in.
+        /// </summary>
+        /// <param name="formOptions">Options to set when instantianting the HTTP context object.</param>
+        /// <param name="httpContextAccessor">Object to be used to access the HTTP context instance.</param>
         public HttpContextFactory(IOptions<FormOptions> formOptions, IHttpContextAccessor httpContextAccessor)
             : this(formOptions, serviceScopeFactory: null, httpContextAccessor: httpContextAccessor)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the DefaultHttpContext class with options passed in.
+        /// </summary>
+        /// <param name="formOptions">Options to set when instantianting the HTTP context object.</param>
+        /// <param name="serviceScopeFactory">Factory object used to create the service scope for the HTTP context.</param>
+        /// <param name="httpContextAccessor">Options to set when instantianting the Default HTTP context object.</param>
         public HttpContextFactory(IOptions<FormOptions> formOptions, IServiceScopeFactory serviceScopeFactory, IHttpContextAccessor httpContextAccessor)
         {
             if (formOptions == null)
@@ -47,6 +70,10 @@ public HttpContextFactory(IOptions<FormOptions> formOptions, IServiceScopeFactor
             _httpContextAccessor = httpContextAccessor;
         }
 
+        /// <summary>
+        /// Initializes a new instance of the DefaultHttpContext class with options passed in.
+        /// </summary>
+        /// <param name="featureCollection">Options to set when instantianting the Default HTTP context object.</param>
         public HttpContext Create(IFeatureCollection featureCollection)
         {
             if (featureCollection == null)
@@ -66,6 +93,10 @@ public HttpContext Create(IFeatureCollection featureCollection)
             return httpContext;
         }
 
+        /// <summary>
+        /// Sets the HTTP context object to null for garbage collection. 
+        /// </summary>
+        /// <param name="httpContext">HTTP context to dispose.</param>
         public void Dispose(HttpContext httpContext)
         {
             if (_httpContextAccessor != null)