documentation

Author: AnakinRaW

src/PetroglyphTools/PG.StarWarsGame.Engine.FileSystem.Test/IO/PetroglyphFileSystemTests.Exist.cs

@@ -166,7 +166,7 @@ public void FileExists_CaseInsensitive_DotSegmentInPath_ReturnsTrue()
             // Input path uses a leading ".\" (dot-segment) AND different casing.
             // After normalization + join: tempDir/./DATA/file.txt
             // File.Exists fast-path fails (case mismatch), so the impl must resolve case-insensitively.
-            // Correct impls must handle "." as a valid path segment that resolves to the current directory,
+            // Correct implementations must handle "." as a valid path segment that resolves to the current directory,
             // not treat it as a literal directory name to look up via GetDirectories.
             var vsb = new ValueStringBuilder();
             var exists = _pgFileSystem.FileExists(@".\DATA\file.txt".AsSpan(), ref vsb, tempDir.AsSpan());
@@ -215,11 +215,9 @@ public void FileExists_CaseInsensitive_MissingIntermediateDirectory_ReturnsFalse
     [InlineData("test.txt", false)]
     public void IsPathFullyQualified_Exists_Internal(string path, bool expected)
     {
-        // This method is internal/private, but we can indirectly test it through FileExists or use reflection if we want to be explicit.
-        // Actually, FileExists calls it.
-        // If it's fully qualified, it doesn't join with gameDirectory.
-        
-        var gameDir = "Z:\\non-existent-dir";
+        // This method is internal/private, but we can indirectly test it through FileExists
+
+        const string gameDir = "Z:\\non-existent-dir";
         var vsb = new ValueStringBuilder();
         _pgFileSystem.FileExists(path.AsSpan(), ref vsb, gameDir.AsSpan());
 

src/PetroglyphTools/PG.StarWarsGame.Engine.FileSystem/IO/PetroglyphFileSystem.Exist.cs

@@ -13,10 +13,7 @@ namespace PG.StarWarsGame.Engine.IO;
 
 public sealed partial class PetroglyphFileSystem
 {
-    internal bool FileExists(
-        ReadOnlySpan<char> filePath, 
-        ref ValueStringBuilder stringBuilder,
-        ReadOnlySpan<char> gameDirectory)
+    internal bool FileExists(ReadOnlySpan<char> filePath, ref ValueStringBuilder stringBuilder, ReadOnlySpan<char> gameDirectory)
     {
         stringBuilder.Length = 0;
 

src/PetroglyphTools/PG.StarWarsGame.Engine.FileSystem/IO/PetroglyphFileSystem.Names.cs

@@ -9,7 +9,18 @@ namespace PG.StarWarsGame.Engine.IO;
 
 public sealed partial class PetroglyphFileSystem
 {
-    
+
+    /// <summary>
+    /// The path string from which to obtain the file name and extension.
+    /// </summary>
+    /// <param name="path"></param>
+    /// <returns>The characters after the last directory separator character in <paramref name="path"/>.
+    /// If the last character of <paramref name="path"/> is a directory or volume separator character, this method returns Empty.
+    /// If <paramref name="path"/> is <see langword="null"/>, this method returns <see langword="null"/>.</returns>
+    /// <remarks>
+    /// The returned value is <see langword="null"/> if the file path is <see langword="null"/>.
+    /// The separator characters used to determine the start of the file name are ("/") and ("\").
+    /// </remarks>
 #if NETSTANDARD2_1 || NET
     [return: NotNullIfNotNull(nameof(path))]
 #endif
@@ -26,6 +37,16 @@ public sealed partial class PetroglyphFileSystem
         return result.ToString();
     }
 
+    /// <summary>
+    /// Returns the file name and extension of a file path that is represented by a read-only character span.
+    /// </summary>
+    /// <param name="path">A read-only span that contains the path from which to obtain the file name and extension.</param>
+    /// <returns>The characters after the last directory separator character in <paramref name="path"/>.</returns>
+    /// <remarks>
+    /// The returned read-only span contains the characters of the path that follow the last separator in path.
+    /// If the last character in path is a volume or directory separator character, the method returns <see cref="ReadOnlySpan{T}.Empty"/>.
+    /// If path contains no separator character, the method returns path.
+    /// </remarks>
     public ReadOnlySpan<char> GetFileName(ReadOnlySpan<char> path)
     {
         if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows)) 
@@ -36,6 +57,11 @@ public ReadOnlySpan<char> GetFileName(ReadOnlySpan<char> path)
         return path.Slice(i < root ? root : i + 1);
     }
 
+    /// <summary>
+    /// Returns the file name of the specified path string without the extension.
+    /// </summary>
+    /// <param name="path">The path of the file.</param>
+    /// <returns>The string returned by <see cref="GetFileName(ReadOnlySpan{char})"/>, minus the last period (.) and all characters following it.</returns>
 #if NETSTANDARD2_1 || NET
     [return: NotNullIfNotNull(nameof(path))]
 #endif
@@ -53,6 +79,11 @@ public ReadOnlySpan<char> GetFileName(ReadOnlySpan<char> path)
             : result.ToString();
     }
 
+    /// <summary>
+    /// Returns the file name without the extension of a file path that is represented by a read-only character span.
+    /// </summary>
+    /// <param name="path">A read-only span that contains the path from which to obtain the file name without the extension.</param>
+    /// <returns>The characters in the read-only span returned by <see cref="GetFileName(ReadOnlySpan{char})"/>, minus the last period (.) and all characters following it.</returns>
     public ReadOnlySpan<char> GetFileNameWithoutExtension(ReadOnlySpan<char> path)
     {
         if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
@@ -65,6 +96,49 @@ public ReadOnlySpan<char> GetFileNameWithoutExtension(ReadOnlySpan<char> path)
             fileName.Slice(0, lastPeriod);
     }
 
+    /// <summary>
+    /// Changes the extension of a path string.
+    /// </summary>
+    /// <param name="path">The path information to modify.</param>
+    /// <param name="extension">The new extension (with or without a leading period). Specify <see langword="null"/> to remove an existing extension from <paramref name="path"/>.</param>
+    /// <returns>
+    /// The modified path information.
+    /// <para>
+    /// If <paramref name="path"/> is <see langword="null"/> or an empty string (""), the path information is returned unmodified.
+    /// If <paramref name="extension"/> is <see langword="null"/>, the returned string contains the specified path with its extension removed.
+    /// If <paramref name="path"/> has no extension, and <paramref name="extension"/> is not <see langword="null"/>,
+    /// the returned path string contains <paramref name="extension"/> appended to the end of <paramref name="path"/>.
+    /// </para>
+    /// </returns>
+    /// <remarks>
+    /// <para>
+    /// If neither <paramref name="path"/> nor <paramref name="extension"/> contains a period (.), ChangeExtension adds the period.
+    /// </para>
+    /// <para>
+    /// The <paramref name="extension"/> parameter can contain multiple periods and any valid path characters, and can be any length. If <paramref name="extension"/> is <see langword="null"/> ,
+    /// the returned string contains the contents of <paramref name="path"/> with the last period and all characters following it removed.
+    /// </para>
+    /// <para>
+    /// If <paramref name="extension"/> is an empty string, the returned path string contains the contents of <paramref name="path"/> with any characters following the last period removed.
+    /// </para>
+    /// <para>
+    /// If <paramref name="path"/> does not have an extension and <paramref name="extension"/> is not <see langword="null"/>,
+    /// the returned string contains <paramref name="path"/> followed by <paramref name="extension"/>.
+    /// </para>
+    /// <para>
+    /// If <paramref name="extension"/> is not <see langword="null"/>  and does not contain a leading period, the period is added.
+    /// </para>
+    /// <para>
+    /// If <paramref name="path"/> contains a multiple extension separated by multiple periods,
+    /// the returned string contains the contents of <paramref name="path"/> with the last period and all characters following it replaced by <paramref name="extension"/>.
+    /// For example, if <paramref name="path"/> is <c>"\Dir1\examples\pathtests.csx.txt"</c> and <paramref name="extension"/> is <c>"cs"</c>,
+    /// the modified path is <c>"\Dir1\examples\pathtests.csx.cs"</c>.
+    /// </para>
+    /// <para>
+    /// It is not possible to verify that the returned results are valid in all scenarios. For example,
+    /// if <paramref name="path"/> is empty, <paramref name="extension"/> is appended.
+    /// </para>
+    /// </remarks>
 #if NETSTANDARD2_1 || NET
     [return: NotNullIfNotNull(nameof(path))]
 #endif
@@ -109,7 +183,13 @@ public ReadOnlySpan<char> GetFileNameWithoutExtension(ReadOnlySpan<char> path)
         return string.Concat(subPath, ".", extension);
 #endif
     }
-    
+
+    /// <summary>
+    /// Returns the directory information for the specified path represented by a character span.
+    /// </summary>
+    /// <param name="path">The path to retrieve the directory information from.</param>
+    /// <returns>Directory information for <paramref name="path"/>, or an empty span if <paramref name="path"/> is <see langword="null"/>,
+    /// an empty span, or a root (such as \, C:, or \server\share).</returns>
     public ReadOnlySpan<char> GetDirectoryName(ReadOnlySpan<char> path)
     {
         if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))

src/PetroglyphTools/PG.StarWarsGame.Engine.FileSystem/IO/PetroglyphFileSystem.PathEqual.cs

@@ -7,7 +7,14 @@ namespace PG.StarWarsGame.Engine.IO;
 
 public sealed partial class PetroglyphFileSystem
 {
-    
+    /// <summary>
+    /// Determines whether two file system paths are considered equal.
+    /// </summary>
+    /// <param name="pathA">The first path to compare.</param>
+    /// <param name="pathB">The second path to compare.</param>
+    /// <returns>
+    /// <see langword="true"/> if the paths are considered equal; otherwise, <see langword="false"/>.
+    /// </returns>
     public bool PathsAreEqual(string pathA, string pathB)
     {
         if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))

src/PetroglyphTools/PG.StarWarsGame.Engine.FileSystem/IO/PetroglyphFileSystem.cs

@@ -34,13 +34,28 @@ public sealed partial class PetroglyphFileSystem
     /// </summary>
     public IFileSystem UnderlyingFileSystem => _underlyingFileSystem;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PetroglyphFileSystem"/> class.
+    /// </summary>
+    /// <param name="serviceProvider">The <see cref="IServiceProvider"/> used to resolve dependencies required by the file system.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="serviceProvider"/> is <see langword="null"/>.</exception>
     public PetroglyphFileSystem(IServiceProvider serviceProvider)
     {
         if (serviceProvider == null)
             throw new ArgumentNullException(nameof(serviceProvider));
         _underlyingFileSystem = serviceProvider.GetRequiredService<IFileSystem>();
     }
 
+    /// <summary>
+    /// Determines whether the specified path ends with a directory separator character.
+    /// </summary>
+    /// <param name="path">The path to check for a trailing directory separator.</param>
+    /// <returns>
+    /// <see langword="true"/> if the path ends with a directory separator character; otherwise, <see langword="false"/>.
+    /// </returns>
+    /// <remarks>
+    /// This method always considers both <c>'/'</c> and <c>'\\'</c> as valid directory separator characters.
+    /// </remarks>
     public bool HasTrailingDirectorySeparator(ReadOnlySpan<char> path)
     {
         return path.Length > 0 && IsDirectorySeparator(path[path.Length - 1]);

src/PetroglyphTools/PG.StarWarsGame.Engine.FileSystem/PG.StarWarsGame.Engine.FileSystem.csproj

@@ -8,9 +8,9 @@
 		<PackageTags>alamo,petroglyph,glyphx</PackageTags>
 	</PropertyGroup>
 	<PropertyGroup>
-		<!--<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+		<!--<TreatWarningsAsErrors>true</TreatWarningsAsErrors>-->
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
-        <InheritDocEnabled>true</InheritDocEnabled>-->
+        <InheritDocEnabled>true</InheritDocEnabled>
 	</PropertyGroup>
 	<PropertyGroup>
 		<IncludeSymbols>true</IncludeSymbols>