updated XmlDoc

Author: AntyaDev

src/NBomber.WebSockets/WebSocket.cs

@@ -6,14 +6,22 @@
 
 namespace NBomber.WebSockets;
 
+/// <summary>
+/// Represents configuration settings for a WebSocket connection.
+/// </summary>
 public class WebSocketConfig
 {
+    /// <summary>
+    /// Gets or sets the default buffer size (in bytes) for WebSocket communication.
+    /// Default is 16 KB (16,384 bytes).
+    /// </summary>
     public int DefaultBufferSize { get; set; } = 16384; // 16KB
 }
 
 /// <summary>
 /// Provides a client for connecting to WebSocket services.
-/// WebSocket type is a wrapper over native .NET <see cref="ClientWebSocket"/> type.
+/// This class wraps the native .NET <see cref="ClientWebSocket"/> and handles sending,
+/// receiving, and managing WebSocket communication with stream-based buffering and message queuing.
 /// </summary>
 public class WebSocket(WebSocketConfig config) : IDisposable
 {
@@ -23,7 +31,14 @@ public class WebSocket(WebSocketConfig config) : IDisposable
     private bool _isListenUpdates = false;
     private long _msgReceivedCount;
 
+    /// <summary>
+    /// Gets the underlying <see cref="ClientWebSocket"/> instance used for communication.
+    /// </summary>
     public ClientWebSocket Client { get; } = new();
+    
+    /// <summary>
+    /// Gets the total number of messages received by the client.
+    /// </summary>
     public long MsgReceivedCount => _msgReceivedCount;
 
     private async Task StartListenOnUpdates()
@@ -71,38 +86,39 @@ private async Task StartListenOnUpdates()
     }
 
     /// <summary>
-    /// This method should be used to connect to a WebSocket server asynchronously.
+    /// Asynchronously connects to a WebSocket server using a string URL.
     /// </summary>
-    /// <param name="url">The URL of the WebSocket server to connect to.</param>
-    /// <param name="cancellationToken">A <see cref="CancellationToken"/> used to propagate notification that the operation should be canceled.</param>
-    /// <exception cref="WebSocketException">Thrown when an error occurs during WebSocket communication.</exception>
-    /// <exception cref="OperationCanceledException">Thrown if the receive operation is canceled by the provided cancellation token.</exception>
+    /// <param name="url">The WebSocket server URL.</param>
+    /// <param name="cancellationToken">Token to signal cancellation.</param>
+    /// <exception cref="WebSocketException">Thrown on connection failure.</exception>
+    /// <exception cref="OperationCanceledException">Thrown if the operation is canceled.</exception>
     public async Task Connect(string url, CancellationToken cancellationToken = default)
     {
         await Client.ConnectAsync(new Uri(url), cancellationToken);
         _ = StartListenOnUpdates();
     }
 
     /// <summary>
-    /// This method should be used to connect to a WebSocket server asynchronously.
+    /// Asynchronously connects to a WebSocket server using a URI.
     /// </summary>
-    /// <param name="uri">The URI of the WebSocket server to connect to.</param>
-    /// <param name="cancellationToken">A <see cref="CancellationToken"/> used to propagate notification that the operation should be canceled.</param>
-    /// <exception cref="WebSocketException">Thrown when an error occurs during WebSocket communication.</exception>
-    /// <exception cref="OperationCanceledException">Thrown if the receive operation is canceled by the provided cancellation token.</exception>
+    /// <param name="uri">The URI of the WebSocket server.</param>
+    /// <param name="cancellationToken">Token to signal cancellation.</param>
+    /// <exception cref="WebSocketException">Thrown on connection failure.</exception>
+    /// <exception cref="OperationCanceledException">Thrown if the operation is canceled.</exception>
     public async Task Connect(Uri uri, CancellationToken cancellationToken = default)
     {
         await Client.ConnectAsync(uri, cancellationToken);
         _ = StartListenOnUpdates();
     }
 
     /// <summary>
-    /// This method should be used to send data on WebSocket asynchronously.
+    /// Sends a UTF-8 encoded text message over the WebSocket connection.
     /// </summary>
     /// <param name="text">The text to be sent. It will be encoded using UTF8 encoding.</param>
-    /// <param name="cancellationToken">A <see cref="CancellationToken"/> used to propagate notification that the operation should be canceled.</param>
-    /// <exception cref="WebSocketException">Thrown when an error occurs during WebSocket communication.</exception>
-    /// <exception cref="OperationCanceledException">Thrown if the receive operation is canceled by the provided cancellation token.</exception>
+    /// <param name="cancellationToken">Token to signal cancellation.</param>
+    /// <returns>A task representing the asynchronous send operation.</returns>
+    /// <exception cref="WebSocketException">Thrown on send failure.</exception>
+    /// <exception cref="OperationCanceledException">Thrown if the operation is canceled.</exception>
     public ValueTask Send(string text, CancellationToken cancellationToken = default)
     {
         using var ms = MsStreamManager.GetStream();
@@ -117,24 +133,26 @@ public ValueTask Send(string text, CancellationToken cancellationToken = default
     }
 
     /// <summary>
-    /// This method should be used to send data on WebSocket asynchronously.
+    /// Sends binary data over the WebSocket connection.
     /// </summary>
-    /// <param name="payload">The binary payload to be sent.</param>
-    /// <param name="cancellationToken">A <see cref="CancellationToken"/> used to propagate notification that the operation should be canceled.</param>
-    /// <exception cref="WebSocketException">Thrown when an error occurs during WebSocket communication.</exception>
-    /// <exception cref="OperationCanceledException">Thrown if the receive operation is canceled by the provided cancellation token.</exception>
+    /// <param name="payload">The binary payload.</param>
+    /// <param name="cancellationToken">Token to signal cancellation.</param>
+    /// <returns>A task representing the asynchronous send operation.</returns>
+    /// <exception cref="WebSocketException">Thrown on send failure.</exception>
+    /// <exception cref="OperationCanceledException">Thrown if the operation is canceled.</exception>
     public ValueTask Send(ReadOnlyMemory<byte> payload, CancellationToken cancellationToken = default)
     {
         return Client.SendAsync(payload, WebSocketMessageType.Binary, true, cancellationToken);
     }
 
     /// <summary>
-    /// This method should be used to receive a WebSocket message from the connected WebSocket asynchronously. 
-    /// This method returns <see cref="WebSocketResponse"/> that should be disposed of after usage.
+    /// Asynchronously receives a WebSocket message. The returned <see cref="WebSocketResponse"/>
+    /// should be disposed after usage to free the underlying stream.
     /// </summary>
-    /// <param name="cancellationToken">A <see cref="CancellationToken"/> used to propagate notification that the operation should be canceled.</param>
-    /// <exception cref="WebSocketException">Thrown when an error occurs during WebSocket communication.</exception>
-    /// <exception cref="OperationCanceledException">Thrown if the receive operation is canceled by the provided cancellation token.</exception>
+    /// <param name="cancellationToken">Token to signal cancellation.</param>
+    /// <returns>A task that returns a <see cref="WebSocketResponse"/>.</returns>
+    /// <exception cref="WebSocketException">Thrown if the client is not listening or in an invalid state.</exception>
+    /// <exception cref="OperationCanceledException">Thrown if the receive is canceled.</exception>
     public async ValueTask<WebSocketResponse> Receive(CancellationToken cancellationToken = default)
     {
         try
@@ -152,18 +170,22 @@ public async ValueTask<WebSocketResponse> Receive(CancellationToken cancellation
     }
 
     /// <summary>
-    /// This method should be used to close WebSocket connection asynchronously.
+    /// Gracefully closes the WebSocket connection with the specified status.
     /// </summary>
-    /// <param name="closeStatus">The WebSocket close status.</param>
-    /// <param name="cancellationToken">A <see cref="CancellationToken"/> used to propagate notification that the operation should be canceled.</param>
-    /// <exception cref="WebSocketException">Thrown when an error occurs during WebSocket communication.</exception>
-    /// <exception cref="OperationCanceledException">Thrown if the receive operation is canceled by the provided cancellation token.</exception>
+    /// <param name="closeStatus">The close status. Default is NormalClosure.</param>
+    /// <param name="cancellationToken">Token to signal cancellation.</param>
+    /// <returns>A task representing the asynchronous close operation.</returns>
+    /// <exception cref="WebSocketException">Thrown on close failure.</exception>
+    /// <exception cref="OperationCanceledException">Thrown if the operation is canceled.</exception>
     public async Task Close(WebSocketCloseStatus closeStatus = WebSocketCloseStatus.NormalClosure, CancellationToken cancellationToken = default)
     {
         await Client.CloseAsync(closeStatus, null, cancellationToken);
         _cts.Cancel();
     }
 
+    /// <summary>
+    /// Disposes the WebSocket client and cancels ongoing operations.
+    /// </summary>
     public void Dispose()
     {
         Client.Dispose();
@@ -172,13 +194,24 @@ public void Dispose()
 }
 
 /// <summary>
-/// Represents a response from a WebSocket. After usage the instance should be disposed.
+/// Represents a response message from the WebSocket.
+/// The response contains message data and its type, and must be disposed to free resources.
 /// </summary>
 public readonly struct WebSocketResponse(RecyclableMemoryStream memoryStream, WebSocketMessageType messageType) : IDisposable
 {
+    /// <summary>
+    /// Gets the message payload as a read-only byte memory block.
+    /// </summary>
     public ReadOnlyMemory<byte> Data { get; } = memoryStream.GetBuffer().AsMemory(0, (int)memoryStream.Length);
+    
+    /// <summary>
+    /// Gets the WebSocket message type (Text, Binary, or Close).
+    /// </summary>
     public WebSocketMessageType MessageType { get; } = messageType;
 
+    /// <summary>
+    /// Releases the memory stream associated with this response.
+    /// </summary>
     public void Dispose()
     {
         memoryStream.Dispose();