From 9b59fe40cfbfbe6d6227289e9c3728bbe787a6eb Mon Sep 17 00:00:00 2001 From: David Fowler Date: Mon, 24 Jun 2019 14:06:01 -0700 Subject: [PATCH] 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 * Apply suggestions from code review Co-Authored-By: Justin Kotalik --- src/Http/Http.Abstractions/src/HttpRequest.cs | 7 ++-- .../Http.Abstractions/src/HttpResponse.cs | 3 +- .../src/ConnectionContext.cs | 35 +++++++++++++++++++ .../src/ConnectionDelegate.cs | 5 +++ .../src/IConnectionBuilder.cs | 15 ++++++++ .../src/IConnectionListener.cs | 16 +++++++++ .../src/IConnectionListenerFactory.cs | 9 +++++ 7 files changed, 86 insertions(+), 4 deletions(-) diff --git a/src/Http/Http.Abstractions/src/HttpRequest.cs b/src/Http/Http.Abstractions/src/HttpRequest.cs index 4a6c58b7e0..1b13dc10cc 100644 --- a/src/Http/Http.Abstractions/src/HttpRequest.cs +++ b/src/Http/Http.Abstractions/src/HttpRequest.cs @@ -99,14 +99,15 @@ namespace Microsoft.AspNetCore.Http public abstract string ContentType { get; set; } /// - /// Gets or sets the RequestBody Stream. + /// Gets or sets the request body . /// - /// The RequestBody Stream. + /// The request body . public abstract Stream Body { get; set; } /// - /// Gets the request body pipe . + /// Gets the request body . /// + /// The request body . public virtual PipeReader BodyReader { get => throw new NotImplementedException(); } /// diff --git a/src/Http/Http.Abstractions/src/HttpResponse.cs b/src/Http/Http.Abstractions/src/HttpResponse.cs index 9df4f095e6..0713d3b365 100644 --- a/src/Http/Http.Abstractions/src/HttpResponse.cs +++ b/src/Http/Http.Abstractions/src/HttpResponse.cs @@ -45,8 +45,9 @@ namespace Microsoft.AspNetCore.Http public abstract Stream Body { get; set; } /// - /// Gets the response body pipe + /// Gets the response body /// + /// The response body . public virtual PipeWriter BodyWriter { get => throw new NotImplementedException(); } /// diff --git a/src/Servers/Connections.Abstractions/src/ConnectionContext.cs b/src/Servers/Connections.Abstractions/src/ConnectionContext.cs index cbbf5ff767..947066ca79 100644 --- a/src/Servers/Connections.Abstractions/src/ConnectionContext.cs +++ b/src/Servers/Connections.Abstractions/src/ConnectionContext.cs @@ -12,22 +12,50 @@ using Microsoft.AspNetCore.Http.Features; namespace Microsoft.AspNetCore.Connections { + /// + /// Encapsulates all information about an individual connection. + /// public abstract class ConnectionContext : IAsyncDisposable { + /// + /// Gets or sets a unique identifier to represent this connection in trace logs. + /// public abstract string ConnectionId { get; set; } + /// + /// Gets the collection of features provided by the server and middleware available on this connection. + /// public abstract IFeatureCollection Features { get; } + /// + /// Gets or sets a key/value collection that can be used to share data within the scope of this connection. + /// public abstract IDictionary Items { get; set; } + /// + /// Gets or sets the that can be used to read or write data on this connection. + /// public abstract IDuplexPipe Transport { get; set; } + /// + /// Triggered when the client connection is closed. + /// public virtual CancellationToken ConnectionClosed { get; set; } + /// + /// Gets or sets the local endpoint for this connection. + /// public virtual EndPoint LocalEndPoint { get; set; } + /// + /// Gets or sets the remote endpoint for this connection. + /// public virtual EndPoint RemoteEndPoint { get; set; } + /// + /// Aborts the underlying connection. + /// + /// An optional describing the reason the connection is being terminated. 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()?.Abort(); } + /// + /// Aborts the underlying connection. + /// public virtual void Abort() => Abort(new ConnectionAbortedException("The connection was aborted by the application via ConnectionContext.Abort().")); + /// + /// Releases resources for the underlying connection. + /// + /// A that completes when resources have been released. public virtual ValueTask DisposeAsync() { return default; diff --git a/src/Servers/Connections.Abstractions/src/ConnectionDelegate.cs b/src/Servers/Connections.Abstractions/src/ConnectionDelegate.cs index dff0384f60..94d8057822 100644 --- a/src/Servers/Connections.Abstractions/src/ConnectionDelegate.cs +++ b/src/Servers/Connections.Abstractions/src/ConnectionDelegate.cs @@ -5,5 +5,10 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.Connections { + /// + /// A function that can process a connection. + /// + /// A representing the connection. + /// A that represents the connection lifetime. When the task completes, the connection will be closed. public delegate Task ConnectionDelegate(ConnectionContext connection); } diff --git a/src/Servers/Connections.Abstractions/src/IConnectionBuilder.cs b/src/Servers/Connections.Abstractions/src/IConnectionBuilder.cs index 5fe3ec25a0..af000827dc 100644 --- a/src/Servers/Connections.Abstractions/src/IConnectionBuilder.cs +++ b/src/Servers/Connections.Abstractions/src/IConnectionBuilder.cs @@ -5,12 +5,27 @@ using System; namespace Microsoft.AspNetCore.Connections { + /// + /// Defines an interface that provides the mechanisms to configure a connection pipeline. + /// public interface IConnectionBuilder { + /// + /// Gets the that provides access to the application's service container. + /// IServiceProvider ApplicationServices { get; } + /// + /// Adds a middleware delegate to the application's connection pipeline. + /// + /// The middleware delegate. + /// The . IConnectionBuilder Use(Func middleware); + /// + /// Builds the delegate used by this application to process connections. + /// + /// The connection handling delegate. ConnectionDelegate Build(); } } diff --git a/src/Servers/Connections.Abstractions/src/IConnectionListener.cs b/src/Servers/Connections.Abstractions/src/IConnectionListener.cs index b98cf5eb07..464a8650f9 100644 --- a/src/Servers/Connections.Abstractions/src/IConnectionListener.cs +++ b/src/Servers/Connections.Abstractions/src/IConnectionListener.cs @@ -8,12 +8,28 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.Connections { + /// + /// Defines an interface that represents a listener bound to a specific . + /// public interface IConnectionListener : IAsyncDisposable { + /// + /// The endpoint that was bound. This may differ from the requested endpoint, such as when the caller requested that any free port be selected. + /// EndPoint EndPoint { get; } + /// + /// Begins an asynchronous operation to accept an incoming connection. + /// + /// The token to monitor for cancellation requests. + /// A that completes when a connection is accepted, yielding the representing the connection. ValueTask AcceptAsync(CancellationToken cancellationToken = default); + /// + /// Stops listening for incoming connections. + /// + /// The token to monitor for cancellation requests. + /// A that represents the un-bind operation. ValueTask UnbindAsync(CancellationToken cancellationToken = default); } } diff --git a/src/Servers/Connections.Abstractions/src/IConnectionListenerFactory.cs b/src/Servers/Connections.Abstractions/src/IConnectionListenerFactory.cs index b28724e1dd..ad68e06c02 100644 --- a/src/Servers/Connections.Abstractions/src/IConnectionListenerFactory.cs +++ b/src/Servers/Connections.Abstractions/src/IConnectionListenerFactory.cs @@ -10,8 +10,17 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.Connections { + /// + /// Defines an interface that provides the mechanisms for binding to various types of s. + /// public interface IConnectionListenerFactory { + /// + /// Creates an bound to the specified . + /// + /// The to bind to. + /// The token to monitor for cancellation requests. + /// A that completes when the listener has been bound, yielding a representing the new listener. ValueTask BindAsync(EndPoint endpoint, CancellationToken cancellationToken = default); } }