API docs for SignalR (#26445)

* API docs for SignalR

* Apply suggestions from code review

Co-authored-by: Stephen Halter <halter73@gmail.com>
Co-authored-by: Pranav K <prkrishn@hotmail.com>

Co-authored-by: Stephen Halter <halter73@gmail.com>
Co-authored-by: Pranav K <prkrishn@hotmail.com>

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