chore: add comment

Author: emako

src/Flucli.Test/Program.cs

@@ -1,18 +1,21 @@
-using System.Text;
-using System.Text.Unicode;
+using Flucli.Utils.Extensions;
+using System.Text;
 
 namespace Flucli.Test;
 
 internal class Program
 {
     static void Main(string[] args)
     {
+        string[] _ = "explorer.exe /select,\"C:\\Windows\\explorer.exe\""
+            .ToArguments().ToArray();
+
         Task.Run(async () =>
         {
             // ---
             Console.WriteLine("CASE1");
             {
-                CliResult result = await @"D:\ema\utils\DouyinLiveRecorder\DouyinLiveRecorder.v3.0.8\DouyinLiveRecorder.exe"
+                CliResult result = await @"test.exe"
                     .WithArguments("")
                     .WithStandardErrorPipe(PipeTarget.ToDelegate((a) =>
                     {

src/Flucli/CliExtensions.cs

@@ -6,21 +6,46 @@ namespace Flucli;
 
 public static class CliExtensions
 {
+    /// <summary>
+    /// Creates a new instance of the Cli class using the provided command-line string.
+    /// </summary>
+    /// <param name="cli">A command-line string to initialize the Cli instance with.</param>
+    /// <returns>A new Cli instance initialized with the given command-line string.</returns>
     public static Cli CreateCli(this string cli)
     {
         return new Cli(cli);
     }
 
+    /// <summary>
+    /// Creates a new instance of the Cli class using a tuple containing a file name and arguments.
+    /// </summary>
+    /// <param name="cli">A tuple where the first item is the file name, and the second item is an enumerable of arguments.</param>
+    /// <returns>A new Cli instance initialized with the given file name and arguments.</returns>
     public static Cli CreateCli(this (string FileName, IEnumerable<string> Arguments) cli)
     {
         return new Cli(cli.FileName).WithArguments(cli.Arguments);
     }
 
+    /// <summary>
+    /// Initializes a Cli instance with the specified command and its arguments.
+    /// </summary>
+    /// <param name="cli">The command to be executed.</param>
+    /// <param name="arguments">A single string of arguments associated with the command.</param>
+    /// <returns>A new Cli instance initialized with the given command and arguments.</returns>
     public static Cli WithArguments(this string cli, string arguments)
     {
         return new Cli(cli).WithArguments(arguments);
     }
 
+    /// <summary>
+    /// Parses a command-line string into a series of chained Cli instances,
+    /// supporting commands separated by a pipe ('|') symbol.
+    /// Note: Parsing commands with pipe symbols in program options is not supported.
+    /// </summary>
+    /// <param name="cli">The command-line string to parse, potentially containing pipe symbols.</param>
+    /// <returns>
+    /// A Cli instance representing the first command in the chain, with linked Cli instances for each subsequent piped command.
+    /// </returns>
     public static Cli ParseCli(this string cli)
     {
         // The command string containing | is uncommon.

src/Flucli/Utils/BufferSizes.cs

@@ -2,6 +2,13 @@
 
 internal static class BufferSizes
 {
+    /// <summary>
+    /// Default buffer size for general stream operations, typically used to optimize data transfer.
+    /// </summary>
     public const int Stream = 81920;
+
+    /// <summary>
+    /// Default buffer size for StreamReader operations, typically used for reading smaller chunks of data efficiently.
+    /// </summary>
     public const int StreamReader = 1024;
 }

src/Flucli/Utils/Extensions/ArgumentExtension.cs

@@ -7,48 +7,73 @@ namespace Flucli.Utils.Extensions;
 
 public static class ArgumentExtension
 {
+    /// <summary>
+    /// Parses a command-line string into individual arguments, preserving quoted sections as single arguments.
+    /// </summary>
+    /// <param name="cli">The command-line string to parse.</param>
+    /// <returns>An IEnumerable of parsed argument strings.</returns>
     public static IEnumerable<string> ToArguments(this string cli)
     {
         List<string> args = [];
         StringBuilder currentArg = new();
-        bool inQuotes = false;
+        bool inQuotes = false; // Tracks if currently inside quotes
 
         for (int i = 0; i < cli.Length; i++)
         {
             char c = cli[i];
 
             if (c == '"')
             {
+                // Toggle quote state when encountering a quote character
                 inQuotes = !inQuotes;
+
+                // Append the quote to the current argument
                 currentArg.Append(c);
             }
             else if (c == ' ' && !inQuotes)
             {
+                // If a space is encountered outside of quotes, treat it as an argument separator
                 if (currentArg.Length > 0)
                 {
+                    // Add the completed argument
                     args.Add(currentArg.ToString());
+
+                    // Clear for the next argument
                     currentArg.Clear();
                 }
             }
             else
             {
+                // Append character to current argument
                 currentArg.Append(c);
             }
         }
 
         if (currentArg.Length > 0)
         {
+            // Add the last argument if it exists
             args.Add(currentArg.ToString());
         }
 
         return args;
     }
 
+    /// <summary>
+    /// Joins a collection of arguments into a single command-line string, quoting arguments as needed.
+    /// </summary>
+    /// <param name="cli">The arguments to join into a command-line string.</param>
+    /// <returns>A single string representing the command-line.</returns>
     public static string ToArguments(this IEnumerable<string> cli)
     {
         return string.Join(" ", cli?.Select(arg => arg.ToQuoteMarkArguments()) ?? []);
     }
 
+    /// <summary>
+    /// Adds quotes to an argument string if necessary, with options for handling existing quotes.
+    /// </summary>
+    /// <param name="arg">The argument string to process.</param>
+    /// <param name="quoteType">Specifies how to handle existing quotes within the argument.</param>
+    /// <returns>The argument string, possibly with added quotes.</returns>
     public static string ToQuoteMarkArguments(this string arg, QuoteReplace quoteType = QuoteReplace.None)
     {
         if (string.IsNullOrEmpty(arg))
@@ -75,6 +100,11 @@ public static string ToQuoteMarkArguments(this string arg, QuoteReplace quoteTyp
         return arg;
     }
 
+    /// <summary>
+    /// Splits a command-line string into a file name and its arguments.
+    /// </summary>
+    /// <param name="cli">The full command-line string.</param>
+    /// <returns>A tuple containing the file name and an enumerable of arguments.</returns>
     public static (string, IEnumerable<string>) ToFileNameWithArguments(this string cli)
     {
         IEnumerable<string> args = cli.ToArguments();
@@ -93,6 +123,11 @@ public static (string, IEnumerable<string>) ToFileNameWithArguments(this string
         }
     }
 
+    /// <summary>
+    /// Converts a plain string to a SecureString, which is a more secure way to handle sensitive information.
+    /// </summary>
+    /// <param name="str">The plain string to convert.</param>
+    /// <returns>A SecureString containing the characters of the original string.</returns>
     public static SecureString ToSecureString(this string str)
     {
         SecureString secureString = new();
@@ -105,10 +140,24 @@ public static SecureString ToSecureString(this string str)
         return secureString;
     }
 
+    /// <summary>
+    /// Options for handling quotes within argument strings.
+    /// </summary>
     public enum QuoteReplace
     {
+        /// <summary>
+        /// No special handling for quotes
+        /// </summary>
         None,
+
+        /// <summary>
+        /// Replace each quote with two quotes
+        /// </summary>
         DoubleQuote,
+
+        /// <summary>
+        /// Escape each quote with a backslash
+        /// </summary>
         BackSlashQuote,
     }
 }

src/Flucli/Utils/Extensions/StreamExtensions.cs

@@ -7,6 +7,13 @@ namespace Flucli.Utils.Extensions;
 
 internal static class StreamExtensions
 {
+    /// <summary>
+    /// Asynchronously copies data from a source stream to a destination stream with an optional auto-flush feature.
+    /// </summary>
+    /// <param name="source">The source stream to read data from.</param>
+    /// <param name="destination">The destination stream to write data to.</param>
+    /// <param name="autoFlush">Whether to flush the destination stream after each write operation.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
     public static async Task CopyToAsync(this Stream source, Stream destination, bool autoFlush, CancellationToken cancellationToken = default)
     {
         byte[] buffer = new byte[BufferSizes.Stream];
@@ -33,6 +40,12 @@ await destination
         }
     }
 
+    /// <summary>
+    /// Asynchronously copies data from a source stream to a destination stream without auto-flush.
+    /// </summary>
+    /// <param name="source">The source stream to read data from.</param>
+    /// <param name="destination">The destination stream to write data to.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
     public static async Task CopyToAsync(this Stream source, Stream destination, CancellationToken cancellationToken)
     {
         byte[] buffer = new byte[BufferSizes.Stream];
@@ -45,6 +58,15 @@ public static async Task CopyToAsync(this Stream source, Stream destination, Can
         }
     }
 
+    /// <summary>
+    /// Asynchronously reads a specified number of characters from a StreamReader into a buffer.
+    /// </summary>
+    /// <param name="reader">The StreamReader to read from.</param>
+    /// <param name="buffer">The character array buffer to store read characters.</param>
+    /// <param name="index">The starting index in the buffer to begin storing read characters.</param>
+    /// <param name="count">The maximum number of characters to read.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <returns>The total number of characters read.</returns>
     public static async Task<int> ReadAsync(this StreamReader reader, char[] buffer, int index, int count, CancellationToken cancellationToken = default)
     {
         _ = reader ?? throw new ArgumentNullException(nameof(reader));

src/Flucli/Utils/Extensions/TaskExtensions.cs

@@ -6,6 +6,14 @@ namespace Flucli.Utils.Extensions;
 
 internal static class TaskExtensions
 {
+    /// <summary>
+    /// Waits for the specified task to complete within the given timeout period or throws a TimeoutException if it doesn't.
+    /// Also accepts a CancellationToken to allow task cancellation.
+    /// </summary>
+    /// <param name="task">The task to wait on.</param>
+    /// <param name="timeout">The maximum time to wait for the task to complete.</param>
+    /// <param name="cancellationToken">The token to observe for cancellation.</param>
+    /// <exception cref="TimeoutException">Thrown if the task does not complete within the specified timeout.</exception>
     public static async Task WaitAsync(this Task task, TimeSpan timeout, CancellationToken cancellationToken)
     {
         Task cancellationTask = Task.Delay(timeout, cancellationToken);
@@ -19,9 +27,20 @@ public static async Task WaitAsync(this Task task, TimeSpan timeout, Cancellatio
         }
     }
 
+    /// <summary>
+    /// Waits for the specified task to complete, allowing cancellation via the CancellationToken.
+    /// </summary>
+    /// <param name="task">The task to wait on.</param>
+    /// <param name="cancellationToken">The token to observe for cancellation.</param>
     public static async Task WaitAsync(this Task task, CancellationToken cancellationToken)
         => await task.WaitAsync(Timeout.InfiniteTimeSpan, cancellationToken).ConfigureAwait(false);
 
+    /// <summary>
+    /// Waits for the specified task to complete within the given timeout period.
+    /// </summary>
+    /// <param name="task">The task to wait on.</param>
+    /// <param name="timeout">The maximum time to wait for the task to complete.</param>
+    /// <exception cref="TimeoutException">Thrown if the task does not complete within the specified timeout.</exception>
     public static async Task WaitAsync(this Task task, TimeSpan timeout)
         => await task.WaitAsync(timeout, CancellationToken.None).ConfigureAwait(false);
 }