Dairai/add http class descriptions (#17349)

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

@@ -5,12 +5,15 @@ using System;
 
 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 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 @@ namespace Microsoft.AspNetCore.Http
         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 @@ using Microsoft.Extensions.DependencyInjection;
 
 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 @@ namespace Microsoft.AspNetCore.Http
         private DefaultConnectionInfo _connection;
         private DefaultWebSocketManager _websockets;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DefaultHttpContext"/> class.
+        /// </summary>
         public DefaultHttpContext()
             : this(new FeatureCollection())
         {
@@ -40,6 +46,10 @@ namespace Microsoft.AspNetCore.Http
             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);
@@ -47,6 +57,13 @@ namespace Microsoft.AspNetCore.Http
             _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 @@ namespace Microsoft.AspNetCore.Http
             _websockets?.Initialize(features, revision);
         }
 
+        /// <summary>
+        /// Uninitialize all the features in the <see cref="DefaultHttpContext" />.
+        /// </summary>
         public void Uninitialize()
         {
             _features = default;
@@ -66,8 +86,20 @@ namespace Microsoft.AspNetCore.Http
             _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 @@ namespace Microsoft.AspNetCore.Http
         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 @@ namespace Microsoft.AspNetCore.Http
             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 @@ namespace Microsoft.AspNetCore.Http
         [EditorBrowsable(EditorBrowsableState.Never)]
         public HttpContext HttpContext => this;
 
+        /// <inheritdoc/>
         public override void Abort()
         {
             LifetimeFeature.Abort();

src/Http/Http/src/HttpContextAccessor.cs

@@ -5,10 +5,14 @@ using System.Threading;
 
 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,6 +8,9 @@ using Microsoft.Extensions.Options;
 
 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
     {
@@ -15,21 +18,41 @@ namespace Microsoft.AspNetCore.Http
         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 @@ namespace Microsoft.AspNetCore.Http
             _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 @@ namespace Microsoft.AspNetCore.Http
             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)

src/Middleware/HttpsPolicy/src/HttpsRedirectionMiddleware.cs

@@ -13,6 +13,9 @@ using Microsoft.Net.Http.Headers;
 
 namespace Microsoft.AspNetCore.HttpsPolicy
 {
+    /// <summary>
+    /// Middleware that redirects non-HTTPS requests to an HTTPS URL.
+    /// </summary>
     public class HttpsRedirectionMiddleware
     {
         private const int PortNotFound = -1;
@@ -26,7 +29,7 @@ namespace Microsoft.AspNetCore.HttpsPolicy
         private readonly ILogger _logger;
 
         /// <summary>
-        /// Initializes the HttpsRedirectionMiddleware
+        /// Initializes <see cref="HttpsRedirectionMiddleware" />.
         /// </summary>
         /// <param name="next"></param>
         /// <param name="options"></param>
@@ -56,13 +59,13 @@ namespace Microsoft.AspNetCore.HttpsPolicy
         }
 
         /// <summary>
-        /// Initializes the HttpsRedirectionMiddleware
+        /// Initializes <see cref="HttpsRedirectionMiddleware" />.
         /// </summary>
         /// <param name="next"></param>
         /// <param name="options"></param>
         /// <param name="config"></param>
         /// <param name="loggerFactory"></param>
-        /// <param name="serverAddressesFeature">The</param>
+        /// <param name="serverAddressesFeature"></param>
         public HttpsRedirectionMiddleware(RequestDelegate next, IOptions<HttpsRedirectionOptions> options, IConfiguration config, ILoggerFactory loggerFactory,
             IServerAddressesFeature serverAddressesFeature)
             : this(next, options, config, loggerFactory)
@@ -71,7 +74,7 @@ namespace Microsoft.AspNetCore.HttpsPolicy
         }
 
         /// <summary>
-        /// Invokes the HttpsRedirectionMiddleware
+        /// Invokes the HttpsRedirectionMiddleware.
         /// </summary>
         /// <param name="context"></param>
         /// <returns></returns>

src/Middleware/HttpsPolicy/src/HttpsRedirectionOptions.cs

@@ -6,7 +6,7 @@ using Microsoft.AspNetCore.Http;
 namespace Microsoft.AspNetCore.HttpsPolicy
 {
     /// <summary>
-    /// Options for the HttpsRedirection middleware
+    /// Options for the HTTPS Redirection Middleware.
     /// </summary>
     public class HttpsRedirectionOptions
     {

src/Servers/HttpSys/src/WebHostBuilderHttpSysExtensions.cs

@@ -9,16 +9,19 @@ using Microsoft.Extensions.Options;
 
 namespace Microsoft.AspNetCore.Hosting
 {
+    /// <summary>
+    /// Provides extensions method to use Http.sys as the server for the web host.
+    /// </summary>    
     public static class WebHostBuilderHttpSysExtensions
     {
         /// <summary>
-        /// Specify HttpSys as the server to be used by the web host.
+        /// Specify Http.sys as the server to be used by the web host.
         /// </summary>
         /// <param name="hostBuilder">
         /// The Microsoft.AspNetCore.Hosting.IWebHostBuilder to configure.
         /// </param>
         /// <returns>
-        /// The Microsoft.AspNetCore.Hosting.IWebHostBuilder.
+        /// A reference to the <see cref="IWebHostBuilder" /> parameter object.
         /// </returns>
         public static IWebHostBuilder UseHttpSys(this IWebHostBuilder hostBuilder)
         {
@@ -38,16 +41,16 @@ namespace Microsoft.AspNetCore.Hosting
         }
 
         /// <summary>
-        /// Specify HttpSys as the server to be used by the web host.
+        /// Specify Http.sys as the server to be used by the web host.
         /// </summary>
         /// <param name="hostBuilder">
         /// The Microsoft.AspNetCore.Hosting.IWebHostBuilder to configure.
         /// </param>
         /// <param name="options">
-        /// A callback to configure HttpSys options.
+        /// A callback to configure Http.sys options.
         /// </param>
         /// <returns>
-        /// The Microsoft.AspNetCore.Hosting.IWebHostBuilder.
+        /// A reference to the <see cref="IWebHostBuilder" /> parameter object.
         /// </returns>
         public static IWebHostBuilder UseHttpSys(this IWebHostBuilder hostBuilder, Action<HttpSysOptions> options)
         {