added comments using AI - 2

Author: kerryjiang

src/SuperSocket.Kestrel/KestrelPipeConnection.cs

@@ -12,10 +12,18 @@ namespace SuperSocket.Kestrel;
 using SuperSocket.Connection;
 using SuperSocket.ProtoBase;
 
+/// <summary>
+/// Represents a pipe connection that integrates with Kestrel's <see cref="ConnectionContext"/>.
+/// </summary>
 public class KestrelPipeConnection : PipeConnectionBase
 {
     private ConnectionContext _context;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="KestrelPipeConnection"/> class with the specified connection context and options.
+    /// </summary>
+    /// <param name="context">The Kestrel connection context.</param>
+    /// <param name="options">The connection options.</param>
     public KestrelPipeConnection(ConnectionContext context, ConnectionOptions options)
         : base(context.Transport.Input, context.Transport.Output, options)
     {
@@ -30,6 +38,11 @@ public KestrelPipeConnection(ConnectionContext context, ConnectionOptions option
         }
     }
 
+    /// <summary>
+    /// Completes the reader asynchronously.
+    /// </summary>
+    /// <param name="reader">The pipe reader to complete.</param>
+    /// <param name="isDetaching">Indicates whether the connection is detaching.</param>
     protected override async ValueTask CompleteReaderAsync(PipeReader reader, bool isDetaching)
     {
         if (!isDetaching)
@@ -38,6 +51,11 @@ protected override async ValueTask CompleteReaderAsync(PipeReader reader, bool i
         }
     }
 
+    /// <summary>
+    /// Completes the writer asynchronously.
+    /// </summary>
+    /// <param name="writer">The pipe writer to complete.</param>
+    /// <param name="isDetaching">Indicates whether the connection is detaching.</param>
     protected override async ValueTask CompleteWriterAsync(PipeWriter writer, bool isDetaching)
     {
         if (!isDetaching)
@@ -46,6 +64,9 @@ protected override async ValueTask CompleteWriterAsync(PipeWriter writer, bool i
         }
     }
 
+    /// <summary>
+    /// Handles the closure of the connection.
+    /// </summary>
     protected override void OnClosed()
     {
         if (!CloseReason.HasValue)
@@ -54,6 +75,9 @@ protected override void OnClosed()
         base.OnClosed();
     }
 
+    /// <summary>
+    /// Closes the connection and disposes the context.
+    /// </summary>
     protected override async void Close()
     {
         var context = _context;
@@ -67,31 +91,57 @@ protected override async void Close()
         }
     }
 
+    /// <summary>
+    /// Updates the last active time when input pipe data is read.
+    /// </summary>
+    /// <param name="result">The result of the pipe read operation.</param>
     protected override void OnInputPipeRead(ReadResult result)
     {
         if (result is { IsCanceled: false, IsCompleted: false })
             UpdateLastActiveTime();
     }
 
+    /// <summary>
+    /// Sends data over the connection asynchronously using a custom write action.
+    /// </summary>
+    /// <param name="write">The action to write data to the pipe writer.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
     public override async ValueTask SendAsync(Action<PipeWriter> write, CancellationToken cancellationToken)
     {
         await base.SendAsync(write, cancellationToken);
         UpdateLastActiveTime();
     }
 
+    /// <summary>
+    /// Sends data over the connection asynchronously.
+    /// </summary>
+    /// <param name="buffer">The data to send.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
     public override async ValueTask SendAsync(ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken)
     {
         await base.SendAsync(buffer, cancellationToken);
         UpdateLastActiveTime();
     }
 
+    /// <summary>
+    /// Sends a package over the connection asynchronously using the specified encoder.
+    /// </summary>
+    /// <typeparam name="TPackage">The type of the package to send.</typeparam>
+    /// <param name="packageEncoder">The encoder to use for the package.</param>
+    /// <param name="package">The package to send.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
     public override async ValueTask SendAsync<TPackage>(IPackageEncoder<TPackage> packageEncoder, TPackage package,
         CancellationToken cancellationToken)
     {
         await base.SendAsync(packageEncoder, package, cancellationToken);
         UpdateLastActiveTime();
     }
 
+    /// <summary>
+    /// Determines whether the specified exception is ignorable.
+    /// </summary>
+    /// <param name="e">The exception to check.</param>
+    /// <returns><c>true</c> if the exception is ignorable; otherwise, <c>false</c>.</returns>
     protected override bool IsIgnorableException(Exception e)
     {
         if (e is IOException ioe && ioe.InnerException != null)

src/SuperSocket.Kestrel/KestrelPipeConnectionExtensions.cs

@@ -9,8 +9,17 @@
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.Logging;
 
+/// <summary>
+/// Provides extension methods for configuring SuperSocket to use Kestrel's pipe-based connection factory.
+/// </summary>
 public static class KestrelPipeConnectionExtensions
 {
+    /// <summary>
+    /// Configures the SuperSocket host to use Kestrel's pipe-based connection factory.
+    /// </summary>
+    /// <param name="hostBuilder">The SuperSocket host builder.</param>
+    /// <param name="options">The options for the socket connection factory. If <c>null</c>, default options are used.</param>
+    /// <returns>The updated SuperSocket host builder.</returns>
     public static ISuperSocketHostBuilder UseKestrelPipeConnection(this ISuperSocketHostBuilder hostBuilder, SocketConnectionFactoryOptions options = null)
     {
         hostBuilder.ConfigureServices((ctx, services) =>

src/SuperSocket.Kestrel/KestrelPipeConnectionFactory.cs

@@ -9,16 +9,32 @@
 using SuperSocket.Server.Abstractions.Connections;
 using Microsoft.AspNetCore.Server.Kestrel.Transport.Sockets;
 
+/// <summary>
+/// Represents a connection factory for creating connections using Kestrel's <see cref="SocketConnectionContextFactory"/>.
+/// </summary>
 public class KestrelPipeConnectionFactory : TcpConnectionFactoryBase
 {
     private readonly SocketConnectionContextFactory _socketConnectionContextFactory;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="KestrelPipeConnectionFactory"/> class with the specified context factory, listen options, connection options, and socket options setter.
+    /// </summary>
+    /// <param name="socketConnectionContextFactory">The factory for creating socket connection contexts.</param>
+    /// <param name="listenOptions">The options for listening to incoming connections.</param>
+    /// <param name="connectionOptions">The options for managing connections.</param>
+    /// <param name="socketOptionsSetter">The setter for configuring socket options.</param>
     public KestrelPipeConnectionFactory(SocketConnectionContextFactory socketConnectionContextFactory, ListenOptions listenOptions, ConnectionOptions connectionOptions, Action<Socket> socketOptionsSetter)
         : base(listenOptions, connectionOptions, socketOptionsSetter, null)
     {
         _socketConnectionContextFactory = socketConnectionContextFactory;
     }
 
+    /// <summary>
+    /// Creates a connection using the specified socket and cancellation token.
+    /// </summary>
+    /// <param name="connection">The socket representing the connection.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the created connection.</returns>
     public override Task<IConnection> CreateConnection(object connection, CancellationToken cancellationToken)
     {
         var socket = connection as Socket;

src/SuperSocket.Kestrel/KestrelPipeConnectionFactoryBuilder.cs

@@ -7,18 +7,32 @@
 
 namespace SuperSocket.Kestrel;
 
+/// <summary>
+/// Represents a builder for creating connection factories using Kestrel's <see cref="SocketConnectionContextFactory"/>.
+/// </summary>
 public class KestrelPipeConnectionFactoryBuilder : IConnectionFactoryBuilder
 {
     private readonly SocketConnectionContextFactory _socketConnectionContextFactory;
 
     private readonly Action<Socket> _socketOptionsSetter;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="KestrelPipeConnectionFactoryBuilder"/> class with the specified context factory and socket options setter.
+    /// </summary>
+    /// <param name="socketConnectionContextFactory">The factory for creating socket connection contexts.</param>
+    /// <param name="socketOptionsSetter">The setter for configuring socket options.</param>
     public KestrelPipeConnectionFactoryBuilder(SocketConnectionContextFactory socketConnectionContextFactory, SocketOptionsSetter socketOptionsSetter)
     {
         _socketConnectionContextFactory = socketConnectionContextFactory;
         _socketOptionsSetter = socketOptionsSetter.Setter;
     }
 
+    /// <summary>
+    /// Builds a connection factory using the specified listen options and connection options.
+    /// </summary>
+    /// <param name="listenOptions">The options for listening to incoming connections.</param>
+    /// <param name="connectionOptions">The options for managing connections.</param>
+    /// <returns>A connection factory for creating connections.</returns>
     public IConnectionFactory Build(ListenOptions listenOptions, ConnectionOptions connectionOptions)
     {
         return new KestrelPipeConnectionFactory(_socketConnectionContextFactory, listenOptions, connectionOptions, _socketOptionsSetter);

src/SuperSocket.Primitives/AsyncParallel.cs

@@ -5,8 +5,19 @@
 
 namespace SuperSocket
 {
+    /// <summary>
+    /// Provides utility methods for executing asynchronous operations in parallel.
+    /// </summary>
     public static class AsyncParallel
     {
+        /// <summary>
+        /// Executes the specified asynchronous operation for each item in the source collection in parallel.
+        /// </summary>
+        /// <typeparam name="TItem">The type of the items in the source collection.</typeparam>
+        /// <param name="source">The source collection of items.</param>
+        /// <param name="operation">The asynchronous operation to execute for each item.</param>
+        /// <param name="maxDegreeOfParallelism">The maximum number of operations to execute in parallel. Default is 5.</param>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         public static async Task ForEach<TItem>(IEnumerable<TItem> source, Func<TItem, Task> operation, int maxDegreeOfParallelism = 5)
         {
             await ForEach(source, operation, new ParallelOptions
@@ -16,6 +27,14 @@ public static async Task ForEach<TItem>(IEnumerable<TItem> source, Func<TItem, T
             });
         }
 
+        /// <summary>
+        /// Executes the specified asynchronous operation for each item in the source collection in parallel with the specified parallel options.
+        /// </summary>
+        /// <typeparam name="TItem">The type of the items in the source collection.</typeparam>
+        /// <param name="source">The source collection of items.</param>
+        /// <param name="operation">The asynchronous operation to execute for each item.</param>
+        /// <param name="parallelOptions">The options for controlling the parallel execution.</param>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         public static async Task ForEach<TItem>(IEnumerable<TItem> source, Func<TItem, Task> operation, ParallelOptions parallelOptions)
         {
             var allTasks = new List<Task>();

src/SuperSocket.Primitives/CancellationTokenSourcePool.cs

@@ -6,15 +6,25 @@ namespace SuperSocket;
 
 #if NET6_0_OR_GREATER
 
+/// <summary>
+/// Provides a pool for reusing <see cref="CancellationTokenSource"/> instances to reduce memory allocations.
+/// </summary>
 public sealed class CancellationTokenSourcePool
 {
     private const int MaxQueueSize = 1024;
 
     private readonly ConcurrentQueue<PooledCancellationTokenSource> _queue = new();
     private int _count;
 
+    /// <summary>
+    /// Gets a shared instance of the <see cref="CancellationTokenSourcePool"/>.
+    /// </summary>
     public static readonly CancellationTokenSourcePool Shared = new();
-    
+
+    /// <summary>
+    /// Rents a <see cref="PooledCancellationTokenSource"/> from the pool.
+    /// </summary>
+    /// <returns>A pooled <see cref="PooledCancellationTokenSource"/>.</returns>
     public PooledCancellationTokenSource Rent()
     {
         if (_queue.TryDequeue(out var cts))
@@ -27,13 +37,18 @@ public PooledCancellationTokenSource Rent()
         return new PooledCancellationTokenSource(this);
     }
 
+    /// <summary>
+    /// Rents a <see cref="PooledCancellationTokenSource"/> from the pool and sets a cancellation delay.
+    /// </summary>
+    /// <param name="delay">The delay after which the token will be canceled.</param>
+    /// <returns>A pooled <see cref="PooledCancellationTokenSource"/>.</returns>
     public PooledCancellationTokenSource Rent(TimeSpan delay)
     {
         var token = Rent();
         token.CancelAfter(delay);
         return token;
     }
-    
+
     private bool Return(PooledCancellationTokenSource cts)
     {
         if (Interlocked.Increment(ref _count) > MaxQueueSize || !cts.TryReset())
@@ -47,24 +62,31 @@ private bool Return(PooledCancellationTokenSource cts)
     }
 
     /// <summary>
-    /// A <see cref="CancellationTokenSource"/> with a back pointer to the pool it came from.
-    /// Dispose will return it to the pool.
+    /// Represents a <see cref="CancellationTokenSource"/> with a back pointer to the pool it came from.
     /// </summary>
-    public sealed class PooledCancellationTokenSource
-        : CancellationTokenSource
+    public sealed class PooledCancellationTokenSource : CancellationTokenSource
     {
         private readonly CancellationTokenSourcePool _pool;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="PooledCancellationTokenSource"/> class with the specified pool.
+        /// </summary>
+        /// <param name="pool">The pool to which this instance belongs.</param>
         public PooledCancellationTokenSource(CancellationTokenSourcePool pool)
         {
             _pool = pool;
         }
 
+        /// <summary>
+        /// Disposes the <see cref="PooledCancellationTokenSource"/> and returns it to the pool if possible.
+        /// </summary>
+        /// <param name="disposing">A value indicating whether the object is being disposed.</param>
         protected override void Dispose(bool disposing)
         {
             if (!disposing)
                 return;
-            // If we failed to return to the pool then dispose
+
+            // If we failed to return to the pool, then dispose
             if (!_pool.Return(this))
             {
                 base.Dispose(disposing);

src/SuperSocket.Primitives/CertificateOptions.cs

@@ -5,49 +5,49 @@
 
 namespace SuperSocket.Server.Abstractions
 {
+    /// <summary>
+    /// Represents configuration options for loading an X.509 certificate.
+    /// </summary>
     public class CertificateOptions
     {
         /// <summary>
-        /// Gets the certificate file path (pfx).
+        /// Gets or sets the certificate file path (pfx).
         /// </summary>
         public string FilePath { get; set; }
 
         /// <summary>
-        /// Gets the password.
+        /// Gets or sets the password for the certificate file.
         /// </summary>
         public string Password { get; set; }
 
         /// <summary>
-        /// Gets the the store where certificate locates.
+        /// Gets or sets the name of the store where the certificate is located.
         /// </summary>
-        /// <value>
-        /// The name of the store.
-        /// </value>
-        public string StoreName { get; set; } = "My";//The X.509 certificate store for personal certificates.
+        public string StoreName { get; set; } = "My"; // The X.509 certificate store for personal certificates.
 
         /// <summary>
-        /// Gets the thumbprint.
+        /// Gets or sets the thumbprint of the certificate.
         /// </summary>
         public string Thumbprint { get; set; }
 
-
         /// <summary>
-        /// Gets the store location of the certificate.
+        /// Gets or sets the store location of the certificate.
         /// </summary>
-        /// <value>
-        /// The store location.
-        /// </value>
-        public StoreLocation StoreLocation { get; set; } = StoreLocation.CurrentUser;//The X.509 certificate store used by the current user.
-
+        public StoreLocation StoreLocation { get; set; } = StoreLocation.CurrentUser; // The X.509 certificate store used by the current user.
 
         /// <summary>
-        /// Gets a value that will be used to instantiate the X509Certificate2 object in the CertificateManager
+        /// Gets or sets the key storage flags used to instantiate the X509Certificate2 object.
         /// </summary>
         public X509KeyStorageFlags KeyStorageFlags { get; set; }
 
+        /// <summary>
+        /// Retrieves the X.509 certificate based on the specified options.
+        /// </summary>
+        /// <returns>The loaded <see cref="X509Certificate"/>.</returns>
+        /// <exception cref="Exception">Thrown if neither <see cref="FilePath"/> nor <see cref="Thumbprint"/> is provided.</exception>
         public X509Certificate GetCertificate()
         {
-            // load certificate from pfx file
+            // Load certificate from pfx file
             if (!string.IsNullOrEmpty(FilePath))
             {
                 string filePath = FilePath;
@@ -59,7 +59,7 @@ public X509Certificate GetCertificate()
 
                 return new X509Certificate2(filePath, Password, KeyStorageFlags);
             }
-            else if (!string.IsNullOrEmpty(Thumbprint)) // load certificate from certificate store
+            else if (!string.IsNullOrEmpty(Thumbprint)) // Load certificate from certificate store
             {
                 using var store = new X509Store((StoreName)Enum.Parse(typeof(StoreName), StoreName), StoreLocation);