Merge pull request #70 from rameel/comment-improvements

Polish comments and fix typos

Author: rameel

src/Ramstack.FileSystem.Abstractions/Utilities/PathTokenizer.cs

@@ -17,7 +17,7 @@ public Enumerator GetEnumerator() =>
         new Enumerator(path);
 
     /// <summary>
-    /// Tokenizes the specified path into a collection of the path components.
+    /// Tokenizes the specified path into a collection of path components.
     /// </summary>
     /// <param name="path">The file path to tokenize.</param>
     /// <returns>

src/Ramstack.FileSystem.Abstractions/VirtualFileSystemExtensions.cs

@@ -97,7 +97,7 @@ public static ValueTask WriteAsync(this IVirtualFileSystem fs, string path, Stre
         fs.GetFile(path).WriteAsync(stream, overwrite, cancellationToken);
 
     /// <summary>
-    /// Asynchronously reads all the text in the file with the specified encoding.
+    /// Asynchronously reads all the text in the file.
     /// </summary>
     /// <param name="fs">The file system to use.</param>
     /// <param name="path">The file from which to read the entire text content.</param>
@@ -124,7 +124,7 @@ public static ValueTask<string> ReadAllTextAsync(this IVirtualFileSystem fs, str
         fs.GetFile(path).ReadAllTextAsync(encoding, cancellationToken);
 
     /// <summary>
-    /// Asynchronously reads all lines of the file with the specified encoding.
+    /// Asynchronously reads all lines of the file.
     /// </summary>
     /// <param name="fs">The file system to use.</param>
     /// <param name="path">The file to read from.</param>

src/Ramstack.FileSystem.Abstractions/VirtualPath.cs

@@ -157,11 +157,11 @@ public static ReadOnlySpan<char> GetDirectoryName(ReadOnlySpan<char> path)
     }
 
     /// <summary>
-    /// Determines if the specified path in a normalized form.
+    /// Determines if the specified path is in a normalized form.
     /// </summary>
     /// <param name="path">The path to test.</param>
     /// <returns>
-    /// <see langword="true" /> if the path in a normalized form;
+    /// <see langword="true" /> if the path is in a normalized form;
     /// otherwise, <see langword="false" />.
     /// </returns>
     public static bool IsNormalized(ReadOnlySpan<char> path)

src/Ramstack.FileSystem.Amazon/AccessControl.cs

@@ -44,7 +44,7 @@ public enum AccessControl
     AwsExecRead,
 
     /// <summary>
-    /// Object Owner gets FULL_CONTROL, Bucket Owner gets READ
+    /// Object Owner gets FULL_CONTROL, Bucket Owner gets READ.
     /// This ACL applies only to objects and is equivalent to private when used with PUT Bucket.
     /// You use this ACL to let someone other than the bucket owner write content (get full control)
     /// in the bucket but still grant the bucket owner read access to the objects.

src/Ramstack.FileSystem.Amazon/S3Directory.cs

@@ -54,7 +54,7 @@ protected override async ValueTask DeleteCoreAsync(CancellationToken cancellatio
         {
             // The maximum number of objects returned is MaxKeys, which is 1000,
             // and the maximum number of objects that can be deleted at once is also 1000.
-            // Therefore, we can rely (sure?) on this and avoid splitting
+            // Therefore, we can rely on this and avoid splitting
             // the retrieved objects into separate batches.
 
             var response = await _fs.AmazonClient

src/Ramstack.FileSystem.Composite/CompositeDirectory.cs

@@ -17,7 +17,7 @@ internal sealed class CompositeDirectory : VirtualDirectory
     /// <summary>
     /// Initializes a new instance of the <see cref="CompositeDirectory"/> class.
     /// </summary>
-    /// <param name="fileSystem">The file system associated with this file.</param>
+    /// <param name="fileSystem">The file system associated with this directory.</param>
     /// <param name="path">The path of the directory.</param>
     public CompositeDirectory(CompositeFileSystem fileSystem, string path) : base(path) =>
         _fs = fileSystem;

src/Ramstack.FileSystem.Composite/CompositeFileSystem.Helpers.cs

@@ -5,15 +5,15 @@ namespace Ramstack.FileSystem.Composite;
 partial class CompositeFileSystem
 {
     /// <summary>
-    /// Tries to flatten the specified <see cref="IVirtualFileSystem"/> into a flat list of the <see cref="IVirtualFileSystem"/>.
+    /// Tries to flatten the specified <see cref="IVirtualFileSystem"/> into a flat list of <see cref="IVirtualFileSystem"/> instances.
     /// </summary>
     /// <remarks>
     /// If the <paramref name="fileSystem"/> is not a <see cref="CompositeFileSystem"/>,
     /// the same instance of the <paramref name="fileSystem"/> is returned.
     /// </remarks>
     /// <param name="fileSystem">The <see cref="IVirtualFileSystem"/> to flatten.</param>
     /// <returns>
-    /// A <see cref="IVirtualFileSystem"/> that represents the flattened version of the specified <see cref="IVirtualFileSystem"/>.
+    /// An <see cref="IVirtualFileSystem"/> that represents the flattened version of the specified <see cref="IVirtualFileSystem"/>.
     /// </returns>
     public static IVirtualFileSystem Flatten(IVirtualFileSystem fileSystem)
     {
@@ -26,29 +26,29 @@ public static IVirtualFileSystem Flatten(IVirtualFileSystem fileSystem)
     }
 
     /// <summary>
-    /// Creates an instance of the <see cref="IVirtualFileSystem"/> from the specified list and flattens it into a flat list of file systems.
+    /// Creates an <see cref="IVirtualFileSystem"/> from the specified list, flattening any nested <see cref="CompositeFileSystem"/> instances.
     /// </summary>
     /// <remarks>
     /// This method returns a <see cref="CompositeFileSystem"/> if more than one file system remains after flattening.
     /// </remarks>
     /// <param name="list">The list of <see cref="IVirtualFileSystem"/> instances to compose and flatten.</param>
     /// <returns>
-    /// A <see cref="IVirtualFileSystem"/> that represents the flattened version of the specified list of the <see cref="IVirtualFileSystem"/>.
+    /// An <see cref="IVirtualFileSystem"/> that represents the flattened version of the specified list of <see cref="IVirtualFileSystem"/> instances.
     /// </returns>
     public static IVirtualFileSystem Create(params IVirtualFileSystem[] list) =>
         list.Length != 1
             ? Create(list.AsEnumerable())
             : Flatten(list[0]);
 
     /// <summary>
-    /// Creates an instance of the <see cref="IVirtualFileSystem"/> from the specified list and flattens it into a flat list of file systems.
+    /// Creates an <see cref="IVirtualFileSystem"/> from the specified list, flattening any nested <see cref="CompositeFileSystem"/> instances.
     /// </summary>
     /// <remarks>
     /// This method returns a <see cref="CompositeFileSystem"/> if more than one file system remains after flattening.
     /// </remarks>
     /// <param name="list">The list of <see cref="IVirtualFileSystem"/> instances to compose and flatten.</param>
     /// <returns>
-    /// A <see cref="IVirtualFileSystem"/> that represents the flattened version of the specified list of the <see cref="IVirtualFileSystem"/>.
+    /// An <see cref="IVirtualFileSystem"/> that represents the flattened version of the specified list of <see cref="IVirtualFileSystem"/> instances.
     /// </returns>
     public static IVirtualFileSystem Create(IEnumerable<IVirtualFileSystem> list)
     {

src/Ramstack.FileSystem.Globbing/Internal/PathHelper.cs

@@ -18,7 +18,7 @@ internal static class PathHelper
     /// <summary>
     /// Determines whether the specified path matches any of the specified patterns.
     /// </summary>
-    /// <param name="path">The path to match for a match.</param>
+    /// <param name="path">The path to test for a match.</param>
     /// <param name="patterns">An array of patterns to match against the path.</param>
     /// <returns>
     /// <see langword="true" /> if the path matches any of the patterns;

src/Ramstack.FileSystem.Physical/PhysicalDirectory.cs

@@ -68,7 +68,7 @@ protected override ValueTask DeleteCoreAsync(CancellationToken cancellationToken
         }
         catch (DirectoryNotFoundException)
         {
-            // The path to the deleting directory may not exist.
+            // The path of the directory being deleted may not exist.
             // This is a safe scenario and does not require further handling.
         }
 

src/Ramstack.FileSystem.Physical/PhysicalFile.cs

@@ -43,7 +43,7 @@ internal PhysicalFile(PhysicalFileSystem fileSystem, string path, string physica
     /// <inheritdoc />
     protected override ValueTask<Stream> OpenReadCoreAsync(CancellationToken cancellationToken)
     {
-        // SequentialScan is a performance hint that requires extra sys-call on non-Windows systems.
+        // SequentialScan is a performance hint that requires an extra system call on non-Windows systems.
         // https://github.com/dotnet/runtime/blob/46c9a4fff83f35ec659e6659050440aadccf3201/src/libraries/System.Private.CoreLib/src/System/IO/File.cs#L694
         var options = OperatingSystem.IsWindows()
             ? FileOptions.Asynchronous | FileOptions.SequentialScan
@@ -119,7 +119,7 @@ protected override ValueTask DeleteCoreAsync(CancellationToken cancellationToken
         }
         catch (DirectoryNotFoundException)
         {
-            // The path to the deleting file may not exist.
+            // The path of the file being deleted may not exist.
             // This is a safe scenario and does not require further handling.
         }