Added some doc comments to bedrock APIs (#11487)

* Added some doc comments to bedrock APIs
- Also cleaned up some HttpContext doc comments

* Apply suggestions from code review

PR feedback

Co-Authored-By: Andrew Stanton-Nurse <andrew@stanton-nurse.com>

* Apply suggestions from code review

Co-Authored-By: Justin Kotalik <jukotali@microsoft.com>

src/Http/Http.Abstractions/src/HttpRequest.cs

@@ -99,14 +99,15 @@ namespace Microsoft.AspNetCore.Http
         public abstract string ContentType { get; set; }
 
         /// <summary>
-        /// Gets or sets the RequestBody Stream.
+        /// Gets or sets the request body <see cref="Stream"/>.
         /// </summary>
-        /// <returns>The RequestBody Stream.</returns>
+        /// <value>The request body <see cref="Stream"/>.</value>
         public abstract Stream Body { get; set; }
 
         /// <summary>
-        /// Gets the request body pipe <see cref="PipeReader"/>.
+        /// Gets the request body <see cref="PipeReader"/>.
         /// </summary>
+        /// <value>The request body <see cref="PipeReader"/>.</value>
         public virtual PipeReader BodyReader { get => throw new NotImplementedException();  }
 
         /// <summary>

src/Http/Http.Abstractions/src/HttpResponse.cs

@@ -45,8 +45,9 @@ namespace Microsoft.AspNetCore.Http
         public abstract Stream Body { get; set; }
 
         /// <summary>
-        /// Gets the response body pipe <see cref="PipeWriter"/>
+        /// Gets the response body <see cref="PipeWriter"/>
         /// </summary>
+        /// <value>The response body <see cref="PipeWriter"/>.</value>
         public virtual PipeWriter BodyWriter { get => throw new NotImplementedException(); }
 
         /// <summary>

src/Servers/Connections.Abstractions/src/ConnectionContext.cs

@@ -12,22 +12,50 @@ using Microsoft.AspNetCore.Http.Features;
 
 namespace Microsoft.AspNetCore.Connections
 {
+    /// <summary>
+    /// Encapsulates all information about an individual connection.
+    /// </summary>
     public abstract class ConnectionContext : IAsyncDisposable
     {
+        /// <summary>
+        /// Gets or sets a unique identifier to represent this connection in trace logs.
+        /// </summary>
         public abstract string ConnectionId { get; set; }
 
+        /// <summary>
+        /// Gets the collection of features provided by the server and middleware available on this connection.
+        /// </summary>
         public abstract IFeatureCollection Features { get; }
 
+        /// <summary>
+        /// Gets or sets a key/value collection that can be used to share data within the scope of this connection.
+        /// </summary>
         public abstract IDictionary<object, object> Items { get; set; }
 
+        /// <summary>
+        /// Gets or sets the <see cref="IDuplexPipe"/> that can be used to read or write data on this connection.
+        /// </summary>
         public abstract IDuplexPipe Transport { get; set; }
 
+        /// <summary>
+        /// Triggered when the client connection is closed.
+        /// </summary>
         public virtual CancellationToken ConnectionClosed { get; set; }
 
+        /// <summary>
+        /// Gets or sets the local endpoint for this connection.
+        /// </summary>
         public virtual EndPoint LocalEndPoint { get; set; }
 
+        /// <summary>
+        /// Gets or sets the remote endpoint for this connection.
+        /// </summary>
         public virtual EndPoint RemoteEndPoint { get; set; }
 
+        /// <summary>
+        /// Aborts the underlying connection.
+        /// </summary>
+        /// <param name="abortReason">An optional <see cref="ConnectionAbortedException"/> describing the reason the connection is being terminated.</param>
         public virtual void Abort(ConnectionAbortedException abortReason)
         {
             // We expect this to be overridden, but this helps maintain back compat
@@ -36,8 +64,15 @@ namespace Microsoft.AspNetCore.Connections
             Features.Get<IConnectionLifetimeFeature>()?.Abort();
         }
 
+        /// <summary>
+        /// Aborts the underlying connection.
+        /// </summary>
         public virtual void Abort() => Abort(new ConnectionAbortedException("The connection was aborted by the application via ConnectionContext.Abort()."));
 
+        /// <summary>
+        /// Releases resources for the underlying connection.
+        /// </summary>
+        /// <returns>A <see cref="ValueTask"/> that completes when resources have been released.</returns>
         public virtual ValueTask DisposeAsync()
         {
             return default;

src/Servers/Connections.Abstractions/src/ConnectionDelegate.cs

@@ -5,5 +5,10 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNetCore.Connections
 {
+    /// <summary>
+    /// A function that can process a connection.
+    /// </summary>
+    /// <param name="connection">A <see cref="ConnectionContext" /> representing the connection.</param>
+    /// <returns>A <see cref="Task"/> that represents the connection lifetime. When the task completes, the connection will be closed.</returns>
     public delegate Task ConnectionDelegate(ConnectionContext connection);
 }

src/Servers/Connections.Abstractions/src/IConnectionBuilder.cs

@@ -5,12 +5,27 @@ using System;
 
 namespace Microsoft.AspNetCore.Connections
 {
+    /// <summary>
+    /// Defines an interface that provides the mechanisms to configure a connection pipeline.
+    /// </summary>
     public interface IConnectionBuilder
     {
+        /// <summary>
+        /// Gets the <see cref="IServiceProvider"/> that provides access to the application's service container.
+        /// </summary>
         IServiceProvider ApplicationServices { get; }
 
+        /// <summary>
+        /// Adds a middleware delegate to the application's connection pipeline.
+        /// </summary>
+        /// <param name="middleware">The middleware delegate.</param>
+        /// <returns>The <see cref="IConnectionBuilder"/>.</returns>
         IConnectionBuilder Use(Func<ConnectionDelegate, ConnectionDelegate> middleware);
 
+        /// <summary>
+        /// Builds the delegate used by this application to process connections.
+        /// </summary>
+        /// <returns>The connection handling delegate.</returns>
         ConnectionDelegate Build();
     }
 }

src/Servers/Connections.Abstractions/src/IConnectionListener.cs

@@ -8,12 +8,28 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNetCore.Connections
 {
+    /// <summary>
+    /// Defines an interface that represents a listener bound to a specific <see cref="EndPoint"/>.
+    /// </summary>
     public interface IConnectionListener : IAsyncDisposable
     {
+        /// <summary>
+        /// The endpoint that was bound. This may differ from the requested endpoint, such as when the caller requested that any free port be selected.
+        /// </summary>
         EndPoint EndPoint { get; }
 
+        /// <summary>
+        /// Begins an asynchronous operation to accept an incoming connection.
+        /// </summary>
+        /// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
+        /// <returns>A <see cref="ValueTask{ConnectionContext}"/> that completes when a connection is accepted, yielding the <see cref="ConnectionContext" /> representing the connection.</returns>
         ValueTask<ConnectionContext> AcceptAsync(CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Stops listening for incoming connections.
+        /// </summary>
+        /// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
+        /// <returns>A <see cref="ValueTask"/> that represents the un-bind operation.</returns>
         ValueTask UnbindAsync(CancellationToken cancellationToken = default);
     }
 }

src/Servers/Connections.Abstractions/src/IConnectionListenerFactory.cs

@@ -10,8 +10,17 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNetCore.Connections
 {
+    /// <summary>
+    /// Defines an interface that provides the mechanisms for binding to various types of <see cref="EndPoint"/>s.
+    /// </summary>
     public interface IConnectionListenerFactory
     {
+        /// <summary>
+        /// Creates an <see cref="IConnectionListener"/> bound to the specified <see cref="EndPoint"/>.
+        /// </summary>
+        /// <param name="endpoint">The <see cref="EndPoint" /> to bind to.</param>
+        /// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
+        /// <returns>A <see cref="ValueTask{IConnectionListener}"/> that completes when the listener has been bound, yielding a <see cref="IConnectionListener" /> representing the new listener.</returns>
         ValueTask<IConnectionListener> BindAsync(EndPoint endpoint, CancellationToken cancellationToken = default);
     }
 }