API docs for SignalR (#26445)

* API docs for SignalR

* Apply suggestions from code review

Co-authored-by: Stephen Halter <[email protected]>
Co-authored-by: Pranav K <[email protected]>

Co-authored-by: Stephen Halter <[email protected]>
Co-authored-by: Pranav K <[email protected]>

Author: 3 people

src/SignalR/clients/csharp/Client.Core/src/HubConnection.cs

@@ -35,8 +35,19 @@ namespace Microsoft.AspNetCore.SignalR.Client
     /// </remarks>
     public partial class HubConnection : IAsyncDisposable
     {
+        /// <summary>
+        /// The default timeout which specifies how long to wait for a message before closing the connection. Default is 30 seconds.
+        /// </summary>
         public static readonly TimeSpan DefaultServerTimeout = TimeSpan.FromSeconds(30); // Server ping rate is 15 sec, this is 2 times that.
+
+        /// <summary>
+        /// The default timeout which specifies how long to wait for the handshake to respond before closing the connection. Default is 15 seconds.
+        /// </summary>
         public static readonly TimeSpan DefaultHandshakeTimeout = TimeSpan.FromSeconds(15);
+
+        /// <summary>
+        /// The default interval that the client will send keep alive messages to let the server know to not close the connection. Default is 15 second interval.
+        /// </summary>
         public static readonly TimeSpan DefaultKeepAliveInterval = TimeSpan.FromSeconds(15);
 
         // This lock protects the connection state.

src/SignalR/clients/csharp/Client.Core/src/HubConnectionBuilder.cs

@@ -80,6 +80,9 @@ public override string ToString()
         }
 
         // Prevents from being displayed in intellisense
+        /// <summary>
+        /// Gets the <see cref="Type"/> of the current instance.
+        /// </summary>
         [EditorBrowsable(EditorBrowsableState.Never)]
         public new Type GetType()
         {

src/SignalR/clients/csharp/Client.Core/src/Microsoft.AspNetCore.SignalR.Client.Core.csproj

@@ -4,6 +4,7 @@
     <Description>Client for ASP.NET Core SignalR</Description>
     <TargetFrameworks>$(DefaultNetFxTargetFramework);netstandard2.0;netstandard2.1</TargetFrameworks>
     <RootNamespace>Microsoft.AspNetCore.SignalR.Client</RootNamespace>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/SignalR/clients/csharp/Client/src/Microsoft.AspNetCore.SignalR.Client.csproj

@@ -1,8 +1,9 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>Client for ASP.NET Core SignalR</Description>
     <TargetFrameworks>$(DefaultNetFxTargetFramework);netstandard2.0</TargetFrameworks>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/SignalR/clients/csharp/Http.Connections.Client/src/Microsoft.AspNetCore.Http.Connections.Client.csproj

@@ -1,8 +1,9 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>Client for ASP.NET Core Connection Handlers</Description>
     <TargetFrameworks>$(DefaultNetFxTargetFramework);netstandard2.0;netstandard2.1</TargetFrameworks>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/SignalR/clients/csharp/Http.Connections.Client/src/NoTransportSupportedException.cs

@@ -10,6 +10,10 @@ namespace Microsoft.AspNetCore.Http.Connections.Client
     /// </summary>
     public class NoTransportSupportedException : Exception
     {
+        /// <summary>
+        /// Constructs the <see cref="NoTransportSupportedException"/> exception with the provided <paramref name="message"/>.
+        /// </summary>
+        /// <param name="message">Message of the exception.</param>
         public NoTransportSupportedException(string message)
             : base(message)
         {

src/SignalR/clients/csharp/Http.Connections.Client/src/TransportFailedException.cs

@@ -10,8 +10,17 @@ namespace Microsoft.AspNetCore.Http.Connections.Client
     /// </summary>
     public class TransportFailedException : Exception
     {
+        /// <summary>
+        /// The name of the transport that failed to connect.
+        /// </summary>
         public string TransportType { get; }
 
+        /// <summary>
+        /// Constructs a <see cref="TransportFailedException"/>.
+        /// </summary>
+        /// <param name="transportType">The name of the transport that failed to connect.</param>
+        /// <param name="message">The reason the transport failed.</param>
+        /// <param name="innerException">An optional extra exception if one was thrown while trying to connect.</param>
         public TransportFailedException(string transportType, string message, Exception innerException = null)
             : base($"{transportType} failed: {message}", innerException)
         {

src/SignalR/common/Http.Connections.Common/src/AvailableTransport.cs

@@ -5,9 +5,19 @@
 
 namespace Microsoft.AspNetCore.Http.Connections
 {
+    /// <summary>
+    /// Part of the <see cref="NegotiationResponse"/> that represents an individual transport and the trasfer formats the transport supports.
+    /// </summary>
     public class AvailableTransport
     {
+        /// <summary>
+        /// A transport available on the server.
+        /// </summary>
         public string Transport { get; set; }
+
+        /// <summary>
+        /// A list of formats supported by the transport. Examples include "Text" and "Binary".
+        /// </summary>
         public IList<string> TransferFormats { get; set; }
     }
 }

src/SignalR/common/Http.Connections.Common/src/Microsoft.AspNetCore.Http.Connections.Common.csproj

@@ -7,6 +7,7 @@
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
     <RootNamespace>Microsoft.AspNetCore.Http.Connections</RootNamespace>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/SignalR/common/Http.Connections.Common/src/NegotiateProtocol.cs

@@ -11,6 +11,9 @@
 
 namespace Microsoft.AspNetCore.Http.Connections
 {
+    /// <summary>
+    /// The protocol for reading and writing negotiate requests and responses.
+    /// </summary>
     public static class NegotiateProtocol
     {
         private const string ConnectionIdPropertyName = "connectionId";
@@ -36,6 +39,11 @@ public static class NegotiateProtocol
         // Used to detect ASP.NET SignalR Server connection attempt
         private static ReadOnlySpan<byte> ProtocolVersionPropertyNameBytes => new byte[] { (byte)'P', (byte)'r', (byte)'o', (byte)'t', (byte)'o', (byte)'c', (byte)'o', (byte)'l', (byte)'V', (byte)'e', (byte)'r', (byte)'s', (byte)'i', (byte)'o', (byte)'n' };
 
+        /// <summary>
+        /// Writes the <paramref name="response"/> to the <paramref name="output"/>.
+        /// </summary>
+        /// <param name="response">The negotiation response generated in response to a negotiation request.</param>
+        /// <param name="output">Where the <paramref name="response"/> is written to as Json.</param>
         public static void WriteResponse(NegotiationResponse response, IBufferWriter<byte> output)
         {
             var reusableWriter = ReusableUtf8JsonWriter.Get(output);
@@ -124,6 +132,11 @@ public static void WriteResponse(NegotiationResponse response, IBufferWriter<byt
             }
         }
 
+        /// <summary>
+        /// Parses a <see cref="NegotiationResponse"/> from the <paramref name="content"/> as Json.
+        /// </summary>
+        /// <param name="content">The bytes of a Json payload that represents a <see cref="NegotiationResponse"/>.</param>
+        /// <returns>The parsed <see cref="NegotiationResponse"/>.</returns>
         public static NegotiationResponse ParseResponse(ReadOnlySpan<byte> content)
         {
             try

src/SignalR/common/Http.Connections.Common/src/NegotiationResponse.cs

@@ -5,14 +5,44 @@
 
 namespace Microsoft.AspNetCore.Http.Connections
 {
+    /// <summary>
+    /// A response to a '/negotiate' request.
+    /// </summary>
     public class NegotiationResponse
     {
+        /// <summary>
+        /// An optional Url to redirect the client to another endpoint.
+        /// </summary>
         public string Url { get; set; }
+
+        /// <summary>
+        /// An optional access token to go along with the Url.
+        /// </summary>
         public string AccessToken { get; set; }
+
+        /// <summary>
+        /// The public ID for the connection.
+        /// </summary>
         public string ConnectionId { get; set; }
+
+        /// <summary>
+        /// The private ID for the connection.
+        /// </summary>
         public string ConnectionToken { get; set; }
+
+        /// <summary>
+        /// The minimum value between the version the client sends and the maximum version the server supports.
+        /// </summary>
         public int Version { get; set; }
+
+        /// <summary>
+        /// A list of transports the server supports.
+        /// </summary>
         public IList<AvailableTransport> AvailableTransports { get; set; }
+
+        /// <summary>
+        /// An optional error during the negotiate. If this is not null the other properties on the response can be ignored.
+        /// </summary>
         public string Error { get; set; }
     }
 }

src/SignalR/common/Http.Connections/src/ConnectionEndpointRouteBuilderExtensions.cs

@@ -11,6 +11,9 @@
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Extension methods on <see cref="IEndpointRouteBuilder"/> that add routes for <see cref="ConnectionHandler"/>s.
+    /// </summary>
     public static class ConnectionEndpointRouteBuilderExtensions
     {
         /// <summary>

src/SignalR/common/Http.Connections/src/ConnectionOptions.cs

@@ -5,6 +5,9 @@
 
 namespace Microsoft.AspNetCore.Http.Connections
 {
+    /// <summary>
+    /// Options used to change behavior of how connections are handled.
+    /// </summary>
     public class ConnectionOptions
     {
         /// <summary>

src/SignalR/common/Http.Connections/src/ConnectionOptionsSetup.cs

@@ -6,10 +6,20 @@
 
 namespace Microsoft.AspNetCore.Http.Connections
 {
+    /// <summary>
+    /// Sets up <see cref="ConnectionOptions"/>.
+    /// </summary>
     public class ConnectionOptionsSetup : IConfigureOptions<ConnectionOptions>
     {
+        /// <summary>
+        /// Default timeout value for disconnecting idle connections.
+        /// </summary>
         public static TimeSpan DefaultDisconectTimeout = TimeSpan.FromSeconds(15);
 
+        /// <summary>
+        /// Sets default values for options if they have not been set yet.
+        /// </summary>
+        /// <param name="options">The <see cref="ConnectionOptions"/>.</param>
         public void Configure(ConnectionOptions options)
         {
             if (options.DisconnectTimeout == null)

src/SignalR/common/Http.Connections/src/Features/IHttpContextFeature.cs

@@ -1,15 +1,27 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// 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;
 using System.Collections.Generic;
 using System.Text;
+using Microsoft.AspNetCore.Connections;
 using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Http.Connections.Features
 {
+    /// <summary>
+    /// Feature set on the <see cref="ConnectionContext"/> that provides access to the underlying <see cref="Http.HttpContext"/>
+    /// associated with the connection if there is one.
+    /// </summary>
     public interface IHttpContextFeature
     {
+        /// <summary>
+        /// The <see cref="Http.HttpContext"/> associated with the connection if available. 
+        /// </summary>
+        /// <remarks>
+        /// Connections can run on top of HTTP transports like WebSockets or Long Polling, or other non-HTTP transports. As a result,
+        /// this API can sometimes return <see langword="null"/> depending on the configuration of your application.
+        /// </remarks>
         HttpContext HttpContext { get; set; }
     }
 }

src/SignalR/common/Http.Connections/src/Features/IHttpTransportFeature.cs

@@ -4,12 +4,20 @@
 using System;
 using System.Collections.Generic;
 using System.Text;
+using Microsoft.AspNetCore.Connections;
 using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Http.Connections.Features
 {
+    /// <summary>
+    /// Feature set on the <see cref="ConnectionContext"/> that exposes the <see cref="HttpTransportType"/>
+    /// the connection is using.
+    /// </summary>
     public interface IHttpTransportFeature
     {
+        /// <summary>
+        /// The <see cref="HttpTransportType"/> the connection is using.
+        /// </summary>
         HttpTransportType TransportType { get; }
     }
 }

src/SignalR/common/Http.Connections/src/HttpConnectionContextExtensions.cs

@@ -7,6 +7,9 @@
 
 namespace Microsoft.AspNetCore.Http.Connections
 {
+    /// <summary>
+    /// Extension method to get the underlying <see cref="HttpContext"/> of the connection if there is one.
+    /// </summary>
     public static class HttpConnectionContextExtensions
     {
         /// <summary>

src/SignalR/common/Http.Connections/src/Microsoft.AspNetCore.Http.Connections.csproj

@@ -6,6 +6,7 @@
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
     <IsPackable>false</IsPackable>
     <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/SignalR/common/Http.Connections/src/WebSocketOptions.cs

@@ -6,8 +6,15 @@
 
 namespace Microsoft.AspNetCore.Http.Connections
 {
+    /// <summary>
+    /// Options used by the WebSockets transport to modify the transports behavior.
+    /// </summary>
     public class WebSocketOptions
     {
+        /// <summary>
+        /// Gets or sets the amount of time the WebSocket transport will wait for a graceful close before starting an ungraceful close.
+        /// </summary>
+        /// <value>Defaults to 5 seconds</value>
         public TimeSpan CloseTimeout { get; set; } = TimeSpan.FromSeconds(5);
 
         /// <summary>

src/SignalR/common/Protocols.Json/src/Microsoft.AspNetCore.SignalR.Protocols.Json.csproj

@@ -8,6 +8,7 @@
     <RootNamespace>Microsoft.AspNetCore.SignalR</RootNamespace>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/SignalR/common/Protocols.MessagePack/src/MessagePackHubProtocolOptions.cs

@@ -6,6 +6,9 @@
 
 namespace Microsoft.AspNetCore.SignalR
 {
+    /// <summary>
+    /// The <see cref="MessagePackHubProtocol"/> options.
+    /// </summary>
     public class MessagePackHubProtocolOptions
     {
         private MessagePackSerializerOptions? _messagePackSerializerOptions;

src/SignalR/common/Protocols.MessagePack/src/Microsoft.AspNetCore.SignalR.Protocols.MessagePack.csproj

@@ -6,6 +6,7 @@
     <RootNamespace>Microsoft.AspNetCore.SignalR</RootNamespace>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/SignalR/common/Protocols.NewtonsoftJson/src/Microsoft.AspNetCore.SignalR.Protocols.NewtonsoftJson.csproj

@@ -6,6 +6,7 @@
     <RootNamespace>Microsoft.AspNetCore.SignalR</RootNamespace>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/SignalR/common/SignalR.Common/src/IInvocationBinder.cs

@@ -3,13 +3,34 @@
 
 using System;
 using System.Collections.Generic;
+using Microsoft.AspNetCore.SignalR.Protocol;
 
 namespace Microsoft.AspNetCore.SignalR
 {
+    /// <summary>
+    /// Class used by <see cref="IHubProtocol"/>s to get the <see cref="Type"/>(s) expected by the hub message being deserialized.
+    /// </summary>
     public interface IInvocationBinder
     {
+        /// <summary>
+        /// Gets the <see cref="Type"/> the invocation represented by the <paramref name="invocationId"/> is expected to contain.
+        /// </summary>
+        /// <param name="invocationId">The ID of the invocation being received.</param>
+        /// <returns>The <see cref="Type"/> the invocation is expected to contain.</returns>
         Type GetReturnType(string invocationId);
+
+        /// <summary>
+        /// Gets the list of <see cref="Type"/>s the method represented by <paramref name="methodName"/> takes as arguments.
+        /// </summary>
+        /// <param name="methodName">The name of the method being called.</param>
+        /// <returns>A list of <see cref="Type"/>s the method takes as arguments.</returns>
         IReadOnlyList<Type> GetParameterTypes(string methodName);
+
+        /// <summary>
+        /// Gets the <see cref="Type"/> the stream item is expected to contain.
+        /// </summary>
+        /// <param name="streamId">The ID of the stream the stream item is a part of.</param>
+        /// <returns>The <see cref="Type"/> of the item the stream contains.</returns>
         Type GetStreamItemType(string streamId);
     }
 }

src/SignalR/common/SignalR.Common/src/Microsoft.AspNetCore.SignalR.Common.csproj

@@ -8,6 +8,7 @@
     <RootNamespace>Microsoft.AspNetCore.SignalR</RootNamespace>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>