#333 Add doc comments for feature interfaces.

src/Microsoft.AspNetCore.Http.Features/IHttpRequestFeature.cs

@@ -5,15 +5,62 @@ using System.IO;
 
 namespace Microsoft.AspNetCore.Http.Features
 {
+    /// <summary>
+    /// Contains the details of a given request. These properties should all be mutable.
+    /// None of these properties should ever be set to null.
+    /// </summary>
     public interface IHttpRequestFeature
     {
+        /// <summary>
+        /// The HTTP-version as defined in RFC 7230. E.g. "HTTP/1.1"
+        /// </summary>
         string Protocol { get; set; }
+
+        /// <summary>
+        /// The request uri scheme. E.g. "http" or "https". Note this value is not included
+        /// in the original request, it is inferred by checking if the transport used a TLS
+        /// connection or not.
+        /// </summary>
         string Scheme { get; set; }
+
+        /// <summary>
+        /// The request method as defined in RFC 7230. E.g. "GET", "HEAD", "POST", etc..
+        /// </summary>
         string Method { get; set; }
+
+        /// <summary>
+        /// The first portion of the request path associated with application root. The value
+        /// is un-escaped. The value may be string.Empty.
+        /// </summary>
         string PathBase { get; set; }
+
+        /// <summary>
+        /// The portion of the request path that identifies the requested resource. The value
+        /// is un-escaped. The value may be string.Empty if <see cref="PathBase"/> contains the
+        /// full path.
+        /// </summary>
         string Path { get; set; }
+
+        /// <summary>
+        /// The query portion of the request-target as defined in RFC 7230. The value
+        /// may be string.Empty. If not empty then the leading '?' will be included. The value
+        /// is in its original form, without un-escaping.
+        /// </summary>
         string QueryString { get; set; }
+
+        /// <summary>
+        /// Headers included in the request, aggregated by header name. The values are not split
+        /// or merged across header lines. E.g. The following headers:
+        /// HeaderA: value1, value2
+        /// HeaderA: value3
+        /// Result in Headers["HeaderA"] = { "value1, value2", "value3" }
+        /// </summary>
         IHeaderDictionary Headers { get; set; }
+
+        /// <summary>
+        /// A <see cref="Stream"/> representing the request body, if any. Stream.Null may be used
+        /// to represent an empty request body.
+        /// </summary>
         Stream Body { get; set; }
     }
 }

src/Microsoft.AspNetCore.Http.Features/IHttpRequestLifetimeFeature.cs

@@ -7,7 +7,17 @@ namespace Microsoft.AspNetCore.Http.Features
 {
     public interface IHttpRequestLifetimeFeature
     {
+        /// <summary>
+        /// A <see cref="CancellationToken"/> that fires if the request is aborted and
+        /// the application should cease processing. The token will not fire if the request
+        /// completes successfully.
+        /// </summary>
         CancellationToken RequestAborted { get; set; }
+
+        /// <summary>
+        /// Forcefully aborts the request if it has not already completed. This will result in
+        /// RequestAborted being triggered.
+        /// </summary>
         void Abort();
     }
 }

src/Microsoft.AspNetCore.Http.Features/IHttpResponseFeature.cs

@@ -7,14 +7,53 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNetCore.Http.Features
 {
+    /// <summary>
+    /// Represents the fields and state of an HTTP response.
+    /// </summary>
     public interface IHttpResponseFeature
     {
+        /// <summary>
+        /// The status-code as defined in RFC 7230. The default value is 200.
+        /// </summary>
         int StatusCode { get; set; }
+
+        /// <summary>
+        /// The reason-phrase as defined in RFC 7230. Note this field is no longer supported by HTTP/2.
+        /// </summary>
         string ReasonPhrase { get; set; }
+
+        /// <summary>
+        /// The response headers to send. Headers with multiple values will be emitted as multiple headers.
+        /// </summary>
         IHeaderDictionary Headers { get; set; }
+
+        /// <summary>
+        /// The <see cref="Stream"/> for writing the response body.
+        /// </summary>
         Stream Body { get; set; }
+
+        /// <summary>
+        /// Indicates if the response has started. If true, the <see cref="StatusCode"/>,
+        /// <see cref="ReasonPhrase"/>, and <see cref="Headers"/> are now immutable, and
+        /// OnStarting should no longer be called.
+        /// </summary>
         bool HasStarted { get; }
+
+        /// <summary>
+        /// Registers a callback to be invoked just before the response starts. This is the
+        /// last chance to modify the <see cref="Headers"/>, <see cref="StatusCode"/>, or
+        /// <see cref="ReasonPhrase"/>.
+        /// </summary>
+        /// <param name="callback">The callback to invoke when starting the response.</param>
+        /// <param name="state">The state to pass into the callback.</param>
         void OnStarting(Func<object, Task> callback, object state);
+
+        /// <summary>
+        /// Registers a callback to be invoked after a response has fully completed. This is
+        /// intended for resource cleanup.
+        /// </summary>
+        /// <param name="callback">The callback to invoke after the response has completed.</param>
+        /// <param name="state">The state to pass into the callback.</param>
         void OnCompleted(Func<object, Task> callback, object state);
     }
 }

src/Microsoft.AspNetCore.Http.Features/IHttpSendFileFeature.cs

@@ -1,13 +1,26 @@
 // 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 System.IO;
 using System.Threading;
 using System.Threading.Tasks;
 
 namespace Microsoft.AspNetCore.Http.Features
 {
+    /// <summary>
+    /// Provides an efficient mechanism for transferring files from disk to the network.
+    /// </summary>
     public interface IHttpSendFileFeature
     {
+        /// <summary>
+        /// Sends the requested file in the response body. This may bypass the IHttpResponseFeature.Body
+        /// <see cref="Stream"/>. A response may include multiple writes.
+        /// </summary>
+        /// <param name="path">The full disk path to the file.</param>
+        /// <param name="offset">The offset in the file to start at.</param>
+        /// <param name="count">The number of bytes to send, or null to send the remainder of the file.</param>
+        /// <param name="cancellation">A <see cref="CancellationToken"/> used to abort the transmission.</param>
+        /// <returns></returns>
         Task SendFileAsync(string path, long offset, long? count, CancellationToken cancellation);
     }
 }

src/Microsoft.AspNetCore.Http.Features/IHttpUpgradeFeature.cs

@@ -8,7 +8,17 @@ namespace Microsoft.AspNetCore.Http.Features
 {
     public interface IHttpUpgradeFeature
     {
+        /// <summary>
+        /// Indicates if the server can upgrade this request to an opaque, bidirectional stream.
+        /// </summary>
         bool IsUpgradableRequest { get; }
+
+        /// <summary>
+        /// Attempt to upgrade the request to an opaque, bidirectional stream. The response status code
+        /// and headers need to be set before this is invoked. Check <see cref="IsUpgradableRequest"/>
+        /// before invoking.
+        /// </summary>
+        /// <returns></returns>
         Task<Stream> UpgradeAsync();
     }
 }

src/Microsoft.AspNetCore.Http.Features/IHttpWebSocketFeature.cs

@@ -8,8 +8,17 @@ namespace Microsoft.AspNetCore.Http.Features
 {
     public interface IHttpWebSocketFeature
     {
+        /// <summary>
+        /// Indicates if this is a WebSocket upgrade request.
+        /// </summary>
         bool IsWebSocketRequest { get; }
 
+        /// <summary>
+        /// Attempts to upgrade the request to a <see cref="WebSocket"/>. Check <see cref="IsWebSocketRequest"/>
+        /// before invoking this.
+        /// </summary>
+        /// <param name="context"></param>
+        /// <returns></returns>
         Task<WebSocket> AcceptAsync(WebSocketAcceptContext context);
     }
 }

src/Microsoft.AspNetCore.Http.Features/ISession.cs

@@ -8,20 +8,55 @@ namespace Microsoft.AspNetCore.Http
 {
     public interface ISession
     {
+        /// <summary>
+        /// A unique identifier for the current session. This is not the same as the session cookie
+        /// since the cookie lifetime may not be the same as the session entry lifetime in the data store.
+        /// </summary>
         string Id { get; }
 
+        /// <summary>
+        /// Enumerates all the keys, if any.
+        /// </summary>
         IEnumerable<string> Keys { get; }
 
+        /// <summary>
+        /// Load the session from the data store. This may throw if the data store is unavailable.
+        /// </summary>
+        /// <returns></returns>
         Task LoadAsync();
 
+        /// <summary>
+        /// Store the session in the data store. This may throw if the data store is unavailable.
+        /// </summary>
+        /// <returns></returns>
         Task CommitAsync();
 
+        /// <summary>
+        /// Retrieve the value of the given key, if present.
+        /// </summary>
+        /// <param name="key"></param>
+        /// <param name="value"></param>
+        /// <returns></returns>
         bool TryGetValue(string key, out byte[] value);
 
+        /// <summary>
+        /// Set the given key and value in the current session. This will throw if the session
+        /// was not established prior to sending the response.
+        /// </summary>
+        /// <param name="key"></param>
+        /// <param name="value"></param>
         void Set(string key, byte[] value);
 
+        /// <summary>
+        /// Remove the given key from the session if present.
+        /// </summary>
+        /// <param name="key"></param>
         void Remove(string key);
 
+        /// <summary>
+        /// Remove all entries from the current session, if any.
+        /// The session cookie is not removed.
+        /// </summary>
         void Clear();
     }
 }