From 8c2c45889117725b512a4a0365f26994720bda1f Mon Sep 17 00:00:00 2001
From: Andrew Stanton-Nurse <andrew@stanton-nurse.com>
Date: Tue, 26 Feb 2019 14:53:44 -0800
Subject: [PATCH] some little xml doc changes

---
 .../csharp/Client.Core/src/HubConnection.cs   | 31 +++++++++++++++++++
 .../src/HttpConnectionContextExtensions.cs    |  9 ++++++
 .../common/SignalR.Common/src/HubException.cs |  4 +++
 .../server/Core/src/HubConnectionContext.cs   |  3 ++
 4 files changed, 47 insertions(+)

diff --git a/src/SignalR/clients/csharp/Client.Core/src/HubConnection.cs b/src/SignalR/clients/csharp/Client.Core/src/HubConnection.cs
index ce525f204f..c6cc4adafa 100644
--- a/src/SignalR/clients/csharp/Client.Core/src/HubConnection.cs
+++ b/src/SignalR/clients/csharp/Client.Core/src/HubConnection.cs
@@ -63,6 +63,31 @@ namespace Microsoft.AspNetCore.SignalR.Client
         private ConnectionState _connectionState;
         private int _serverProtocolMinorVersion;
 
+        /// <summary>
+        /// Occurs when the connection is closed, either by a call to <see cref="StopAsync(CancellationToken)"/> or a connection 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 from a call to <see cref="StopAsync(CancellationToken)"/>, 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
@@ -985,11 +1010,17 @@ namespace Microsoft.AspNetCore.SignalR.Client
             }
         }
 
+        /// <summary>
+        /// This method is for internal framework use and should not be called by user code.
+        /// </summary>
         public void ResetSendPing()
         {
             Volatile.Write(ref _nextActivationSendPing, (DateTime.UtcNow + KeepAliveInterval).Ticks);
         }
 
+        /// <summary>
+        /// This method is for internal framework use and should not be called by user code.
+        /// </summary>
         public void ResetTimeout()
         {
             Volatile.Write(ref _nextActivationServerTimeout, (DateTime.UtcNow + ServerTimeout).Ticks);
diff --git a/src/SignalR/common/Http.Connections/src/HttpConnectionContextExtensions.cs b/src/SignalR/common/Http.Connections/src/HttpConnectionContextExtensions.cs
index 9c22c75834..9275d0c4e2 100644
--- a/src/SignalR/common/Http.Connections/src/HttpConnectionContextExtensions.cs
+++ b/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;
diff --git a/src/SignalR/common/SignalR.Common/src/HubException.cs b/src/SignalR/common/SignalR.Common/src/HubException.cs
index cb87c50c10..569437573c 100644
--- a/src/SignalR/common/SignalR.Common/src/HubException.cs
+++ b/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
     {
diff --git a/src/SignalR/server/Core/src/HubConnectionContext.cs b/src/SignalR/server/Core/src/HubConnectionContext.cs
index 895a673184..86b735cd35 100644
--- a/src/SignalR/server/Core/src/HubConnectionContext.cs
+++ b/src/SignalR/server/Core/src/HubConnectionContext.cs
@@ -19,6 +19,9 @@ using Microsoft.Extensions.Logging;
 
 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();