Improve docs with gpt4

Sources/FileSugar/FileAsserter.swift

@@ -3,6 +3,7 @@ import Foundation
 public final class FileAsserter {
    /**
     * Asserts if a file or folder exists
+    * - Description: Determines if the specified file or folder exists at the given path.
     * ## Examples:
     * FileAsserter.exists(path: NSString(string: "~/Desktop/del.txt").expandingTildeInPath) // true or false (remember to expand the tildePath)
     * - Parameter path: The path of the file or folder to check for existence
@@ -17,6 +18,7 @@ public final class FileAsserter {
 
    /**
     * Asserts if a directory has files
+    * - Description: Determines if the specified directory at the given path contains any files.
     * ## Examples:
     * FileAsserter.hasContent(filePath: NSString(string: "~/Desktop/").expandingTildeInPath)
     * - Parameter filePath: The path of the directory to check for files

Sources/FileSugar/FileModifier.swift

@@ -3,7 +3,10 @@ import Foundation
 public final class FileModifier {
    /**
     * Moves a file from one location to another
+    * - Description: Moves a file from its current location to a new location specified by the user.
     * - Remark: Paths must be created with: URL(fileURLWithPath: directory) and then .path
+    * ## Examples:
+    * FileModifier.move("~/Desktop/old.txt".tildePath, "~/Desktop/newFolder/old.txt".tildePath) // returns true if the file was successfully moved
     * - Parameters:
     *    - fromURL: The path of the file to move
     *    - toURL: The path of the destination for the file
@@ -23,7 +26,10 @@ public final class FileModifier {
    }
    /**
     * Copies a file to another location
+    * - Description: Copies a file from its current location to a new location specified by the user.
     * - Remark: Paths must be created with: URL(fileURLWithPath: directory) and then .path
+    * ## Examples:
+    * FileModifier.copy("~/Desktop/old.txt".tildePath, "~/Desktop/newFolder/old.txt".tildePath) // returns true if the file was successfully copied
     * - Parameters:
     *   - fromURL: The path of the file to copy
     *   - toURL: The path of the destination for the copied file
@@ -42,9 +48,9 @@ public final class FileModifier {
          return false // return false if the file copy operation failed
       }
    }
-
    /**
     * Writes a string to a file
+    * - Description: Writes the provided string content to the file at the specified path. If the file does not exist, it is created. If the file exists, its contents are overwritten.
     * - Examples:
     * FileModifier.write("~/Desktop/del.txt".tildePath, "test") // returns true or false depending on if something was written or not
     * - Remark: This method overwrites data to files that already exist as well
@@ -65,6 +71,7 @@ public final class FileModifier {
    }
    /**
     * Write data to path
+    * - Description: Writes the provided data to the file at the specified path. If the file does not exist, it is created. This method is useful for writing raw data like binary content.
     * ## Examples:
     * FileModifier.write("~/Desktop/del.txt".tildePath, data) // returns true or false depending on if something was written or not
     * Fixme: this should throw?
@@ -84,6 +91,7 @@ public final class FileModifier {
    }
    /**
     * Create a directory at a path
+    * - Description: Creates a directory at the specified path. If any intermediate directories do not exist, they will be created as well.
     * - Remark: Also creates entire structures of folders say if non of the folders in path desktop/temp/tmp/blabla already exists, then all 3 folders will be created
     * ## Examples:
     * FileModifier.createDir("~/Desktop/temp/".tildePath) // returns true or false depending on if something was created or not
@@ -101,6 +109,9 @@ public final class FileModifier {
    }
    /**
     * Deletes a file at a specific path
+    * - Description: Deletes the file at the specified path. This operation is irreversible.
+    * Example:
+    * FileModifier.delete("~/Desktop/old_file.txt".tildePath) // returns true if the file was successfully deleted
     * - Parameter path: The path of the file to delete
     * - Returns: A boolean value indicating whether the file was successfully deleted
     */
@@ -117,6 +128,9 @@ public final class FileModifier {
    }
    /**
     * Renames a file
+    * - Description: Renames the file at the specified path to a new path. This operation changes the file's location and/or its name within the filesystem.
+    * Example:
+    * FileModifier.rename("~/Desktop/old_name.txt".tildePath, "~/Desktop/new_name.txt".tildePath) // returns true if the file was successfully renamed
     * - Parameters:
     *   - fromURL: The path of the file to rename
     *   - toURL: The new path for the renamed file
@@ -134,6 +148,9 @@ public final class FileModifier {
    }
    /**
     * Creates a folder at a specific path
+    * - Description: Creates a folder at the specified path. This operation includes the creation of intermediate directories if they do not exist.
+    * Example:
+    * FileModifier.createFolder("~/Desktop/new_folder".tildePath) // returns true if the folder was successfully created
     * - Parameter path: The path of the folder to create
     * - Returns: A boolean value indicating whether the folder was successfully created
     */
@@ -149,6 +166,9 @@ public final class FileModifier {
    }
    /**
     * Append text to end of file
+    * - Description: Appends the specified text to the end of the file at the given path.
+    * Example:
+    * FileModifier.append("~/Desktop/log.txt".tildePath, "New log entry") // returns true if the text was successfully appended
     * - Parameters:
     *   - path: The path of the file to append to
     *   - text: The text to append to the file
@@ -160,6 +180,9 @@ public final class FileModifier {
 
    /**
     * Append text to file at index
+    * - Description: Appends the specified text to the file at the given path and index. If the index is beyond the current file length, the text will be appended at the end.
+    * Example:
+    * FileModifier.append("~/Desktop/log.txt".tildePath, "New log entry", index: 10) // returns true if the text was successfully appended at the specified index
     * - Parameters:
     *   - path: The path of the file to append to
     *   - text: The text to append to the file

Sources/FileSugar/FileParser.swift

@@ -7,6 +7,11 @@ import Foundation
 public final class FileParser {
    /**
     * Get data for URL
+    * - Description: Retrieves the raw data from the file located at the specified URL.
+    * ## Examples:
+    * let url = URL(fileURLWithPath: "~/Desktop/example.txt")
+    * let data = FileParser.data(url: url)
+    * Swift.print(data) // Output: Optional(<file data>)
     * - Parameter url: The URL of the file to get data from
     * - Returns: The data of the file at the specified URL, or nil if an error occurred
     */
@@ -20,6 +25,11 @@ public final class FileParser {
    }
    /**
     * Get data for file at a specific path
+    * - Description: Retrieves the raw data from the file located at the specified file path.
+    * ## Examples:
+    * let filePath = "~/Desktop/example.txt"
+    * let data = FileParser.data(filePath: filePath.tildePath)
+    * Swift.print(data) // Output: Optional(<file data>)
     * - Parameter filePath: The path of the file to get data from
     * - Returns: The data of the file at the specified path, or nil if an error occurred
     */
@@ -35,6 +45,7 @@ public final class FileParser {
    }
    /**
     * Returns string content from a file at file location "path"
+    * - Description: Retrieves the string content from the file located at the specified path.
     * - Important: ⚠️️ Remember to expand the path with the .tildePath call, if it's a tilde path
     * - Remark: Supports syntax like this: `/Users/John/Desktop/temp/../test.txt` (the temp folder is excluded in this case)
     * ## Examples:
@@ -59,6 +70,7 @@ public final class FileParser {
    }
    /**
     * Get the string content of a resource file in the main bundle
+    * - Description: Retrieves the string content from a resource file located within the app's main bundle.
     * ## Examples:
     * Swift.print(FileParser.content(FilePathParser.resourcePath() + "/temp.bundle/test.txt"))
     * - Parameters:
@@ -74,6 +86,7 @@ public final class FileParser {
    }
    /**
     * Get the modification date of a file at a specific path
+    * - Description: Retrieves the modification date of the file at the specified path.
     * - Remark: Make sure the file exists with: `FileAsserter.exists("some path here")`
     * - Parameter filePath: The absolute path of the file to get the modification date of
     * ## Examples:
@@ -91,6 +104,7 @@ public final class FileParser {
    }
    /**
     * Returns paths of content in a directory
+    * - Description: Retrieves the paths of all files and directories within the specified directory.
     * - Note: This method returns the paths of all files and directories in the specified directory
     * - Remark: This is the root folder of the main hard drive on your computer
     * ## Examples:
@@ -111,14 +125,21 @@ public final class FileParser {
    }
    /**
     * Returns temporary directory path
+    * - Description: Retrieves the path to the system's temporary directory, which is used to store temporary files and data.
+    * ## Examples:
+    * let tempDirectoryPath = FileParser.tempPath
+    * Swift.print("Temporary directory path: \(tempDirectoryPath)")
     * - Returns: The path of the temporary directory
     */
    public static var tempPath: String {
       NSTemporaryDirectory() as String // get the path of the temporary directory
    }
-
    /**
     * Returns the current directory path
+    * - Description: Retrieves the path of the current working directory.
+    * ## Examples:
+    * let currentDirectoryPath = FileParser.curDir
+    * Swift.print("Current directory path: \(currentDirectoryPath)")
     * - Returns: The path of the current directory
     */
    public static var curDir: String {
@@ -134,6 +155,7 @@ import Cocoa
 extension FileParser {
    /**
     * Returns an xml instance comprised of the string content at location path
+    * - Description: Parses the XML content from the specified file path and returns the root XML element.
     * ## Examples:
     * xml("~/Desktop/assets/xml/table.xml".tildePath) // Output: XML instance
     * - Important: ⚠️️ Remember to expand the "path" with the tildePath call before you call xml(path)
@@ -152,6 +174,9 @@ extension FileParser {
    }
    /**
     * Example method that demonstrates how to use an NSOpenPanel to choose a file and get its content
+    * - Description: Demonstrates the use of NSOpenPanel to select a file and retrieve its content.
+    * ## Examples:
+    * FileParser.modalExample() // Opens a file dialog, user selects a file, prints its content
     * - Remark: This method is an example and should be modified to fit your specific use case
     */
    private static func modalExample() {

Sources/FileSugar/FileUtils.swift

@@ -6,6 +6,7 @@ import Cocoa
 class FileUtils {
    /**
     * Shows where a file is in a finder window
+    * - Description: Opens the Finder at the specified file path, allowing the user to view the location of the file or folder in the macOS Finder.
     * ## Examples:
     * showFileInFinder("~/dev/Element") -> shows the file or folder in finder
     * - Parameter filePath: The path of the file or folder to show in Finder

Sources/FileSugar/common/String+Extension.swift

@@ -3,6 +3,10 @@ import Foundation
 extension String {
    /**
     * From user agnostic to absolute URL
+    * ## Example:
+    * let path = "~/Documents/example.txt"
+    * let absolutePath = path.tildePath // "/Users/username/Documents/example.txt"
+    * - Description: Converts a user-agnostic path (starting with "~") to an absolute path by expanding the tilde to the current user's home directory.
     */
    internal var tildePath: String {
       // Convert the string to an NSString and expand the tilde in the path

Sources/FileSugar/path/FilePathAsserter.swift

@@ -3,6 +3,10 @@ import Foundation
 public final class FilePathAsserter {
     /**
      * Tests if a path is absolute or relative
+     * - Description: Determines if the provided path is absolute based on the specified path separator.
+     * ## Example:
+     * let path = "/Users/username/Documents"
+     * let isAbsolutePath = FilePathAsserter.isAbsolute(path) // true
      * - Parameters:
      *   - path: The path to test
      *   - pathSeperator: The path separator to use (default is "/")
@@ -13,6 +17,10 @@ public final class FilePathAsserter {
     }
     /**
      * Tests if a path contains a relative path (i.e. "../")
+     * - Description: Determines if the provided path contains a relative path segment such as "../", which indicates a step back in the directory hierarchy.
+     * ## Example:
+     * let path = "../User/Documents/example.txt"
+     * let containsBacklash = FilePathAsserter.isBacklash(path) // true
      * - Parameter path: The path to test
      * - Returns: True if the path contains a relative path, false otherwise
      */
@@ -21,6 +29,10 @@ public final class FilePathAsserter {
     }
     /**
      * Tests if a path is a file path (i.e. starts with a path separator or "../")
+     * - Description: Determines if the provided path is a file path by checking if it starts with a path separator or a relative path prefix.
+     * ## Example:
+     * let path = "/Users/username/Documents/example.txt"
+     * let isFilePath = FilePathAsserter.isFilePath(path) // true
      * - Parameters:
      *   - path: The path to test
      *   - pathSeperator: The path separator to use (default is "/")
@@ -32,6 +44,10 @@ public final class FilePathAsserter {
     }
     /**
      * Tests if a path is a tilde path (i.e. starts with "~")
+     * - Description: Determines if the provided path starts with a tilde ("~"), which typically represents the home directory in Unix-like systems.
+     * ## Example:
+     * let path = "~/Documents/example.txt"
+     * let isTildePath = FilePathAsserter.isTildePath(path) // true
      * - Parameter path: The path to test
      * - Returns: True if the path is a tilde path, false otherwise
      */

Sources/FileSugar/path/FilePathModifier.swift

@@ -1,10 +1,15 @@
 import Foundation
 /**
  * There is also tildify which makes file paths user agnostic (~ instad of hardocded user)
+ * - Description: Provides methods for modifying and handling file paths, such as normalizing paths or expanding them to absolute paths.
  */
 public final class FilePathModifier {
    /**
     * Normalizes a file path by resolving any symbolic links, removing any redundant path components, and returning an absolute path
+    * - Description: This method takes a potentially complex or relative file path and simplifies it by resolving symbolic links, normalizing path components like "." and "..", and converting it to an absolute path if necessary. This ensures that the path is in a standard and predictable format, which is useful for file operations that require a canonical path.
+    * ## Example:
+    * let originalPath = "~/Documents/../Desktop/./file.txt"
+    * let normalizedPath = FilePathModifier.normalize(originalPath) // "/Users/username/Desktop/file.txt"
     * - Parameter path: The path to normalize
     * - Returns: The normalized path, or nil if the path cannot be normalized
     */
@@ -22,6 +27,7 @@ import Cocoa
 extension FilePathModifier {
    /**
     * Expands a file path to an absolute path
+    * - Description: Expands a given file path into its absolute path form. This method handles tilde paths, relative paths, and absolute paths, ensuring the output is an absolute path. If a base URL is provided, it is used as the starting point for relative paths.
     * - Parameters:
     *   - filePath: The file path to expand
     *   - baseURL: The base URL to use when expanding relative paths (default is "")