SignalR additional xml docs (#7980)

Reviewed our xml docs as both ramping back up after leave and docathon. Things look pretty good, added a few things to some public methods.

Author: analogrelay

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

@@ -63,13 +63,40 @@ public partial class HubConnection
         private ConnectionState _connectionState;
         private int _serverProtocolMinorVersion;
 
+        /// <summary>
+        /// Occurs when the connection is closed. The connection could be closed due to an error or due to either the server or client intentionally
+        /// closing the connection without error.
+        /// </summary>
+        /// <remarks>
+        /// If this event was triggered from a connection error, the <see cref="Exception"/> that occurred will be passed in as the
+        /// sole argument to this handler. If this event was triggered intentionally by either the client or server, then
+        /// the argument will be <see langword="null"/>.
+        /// </remarks>
+        /// <example>
+        /// The following example attaches a handler to the <see cref="Closed"/> event, and checks the provided argument to determine
+        /// if there was an error:
+        ///
+        /// <code>
+        /// connection.Closed += (exception) =>
+        /// {
+        ///     if (exception == null)
+        ///     {
+        ///         Console.WriteLine("Connection closed without error.");
+        ///     }
+        ///     else
+        ///     {
+        ///         Console.WriteLine($"Connection closed due to an error: {exception.Message}");
+        ///     }
+        /// };
+        /// </code>
+        /// </example>
         public event Func<Exception, Task> Closed;
 
         // internal for testing purposes
         internal TimeSpan TickRate { get; set; } = TimeSpan.FromSeconds(1);
 
         /// <summary>
-        /// Gets or sets the server timeout interval for the connection. 
+        /// Gets or sets the server timeout interval for the connection.
         /// </summary>
         /// <remarks>
         /// The client times out if it hasn't heard from the server for `this` long.
@@ -510,7 +537,7 @@ private void LaunchStreams(Dictionary<string, object> readers, CancellationToken
             }
         }
 
-        // this is called via reflection using the `_sendStreamItems` field 
+        // this is called via reflection using the `_sendStreamItems` field
         private async Task SendStreamItems<T>(string streamId, ChannelReader<T> reader, CancellationToken token)
         {
             Log.StartingStream(_logger, streamId);
@@ -849,7 +876,7 @@ private async Task HandshakeAsync(ConnectionState startingConnectionState, Cance
                     }
                 }
             }
-            
+
             // shutdown if we're unable to read handshake
             // Ignore HubException because we throw it when we receive a handshake response with an error
             // And because we already have the error, we don't need to log that the handshake failed
@@ -1139,7 +1166,7 @@ public void Dispose()
         private class InvocationHandlerList
         {
             private readonly List<InvocationHandler> _invocationHandlers;
-            // A lazy cached copy of the handlers that doesn't change for thread safety. 
+            // A lazy cached copy of the handlers that doesn't change for thread safety.
             // Adding or removing a handler sets this to null.
             private InvocationHandler[] _copiedHandlers;
 

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

@@ -9,6 +9,15 @@ namespace Microsoft.AspNetCore.Http.Connections
 {
     public static class HttpConnectionContextExtensions
     {
+        /// <summary>
+        /// Gets the <see cref="HttpContext"/> associated with the connection, if there is one.
+        /// </summary>
+        /// <param name="connection">The <see cref="ConnectionContext"/> representing the connection.</param>
+        /// <returns>The <see cref="HttpContext"/> associated with the connection, or <see langword="null"/> if the connection is not HTTP-based.</returns>
+        /// <remarks>
+        /// SignalR connections can run on top of HTTP transports like WebSockets or Long Polling, or other non-HTTP transports. As a result,
+        /// this method can sometimes return <see langword="null"/> depending on the configuration of your application.
+        /// </remarks>
         public static HttpContext GetHttpContext(this ConnectionContext connection)
         {
             return connection.Features.Get<IHttpContextFeature>()?.HttpContext;

src/SignalR/common/SignalR.Common/src/HubException.cs

@@ -9,6 +9,10 @@ namespace Microsoft.AspNetCore.SignalR
     /// <summary>
     /// The exception thrown from a hub when an error occurs.
     /// </summary>
+    /// <remarks>
+    /// Exceptions often contain sensitive information, such as connection information. Because of this, SignalR does not expose the details
+    /// of exceptions that occur on the server to the client. However, instances of <see cref="HubException"/> <b>are</b> sent to the client.
+    /// </remarks>
     [Serializable]
     public class HubException : Exception
     {

src/SignalR/server/Core/src/HubConnectionContext.cs

@@ -19,6 +19,9 @@
 
 namespace Microsoft.AspNetCore.SignalR
 {
+    /// <summary>
+    /// Encapsulates all information about an individual connection to a SignalR Hub.
+    /// </summary>
     public class HubConnectionContext
     {
         private static readonly Action<object> _cancelReader = state => ((PipeReader)state).CancelPendingRead();