Introduce a GenericError struct + improve documentation & messages

Author: Jeehut

Sources/ErrorKit/BuiltInErrors/DatabaseError.swift

@@ -1,22 +1,103 @@
 import Foundation
 
 /// Represents errors that occur during database operations.
+///
+/// # Examples of Use
+///
+/// ## Handling Database Connections
+/// ```swift
+/// struct DatabaseConnection {
+///     func connect() throws(DatabaseError) {
+///         guard let socket = openNetworkSocket() else {
+///             throw .connectionFailed
+///         }
+///         // Successful connection logic
+///     }
+/// }
+/// ```
+///
+/// ## Managing Record Operations
+/// ```swift
+/// struct UserRepository {
+///     func findUser(byId id: String) throws(DatabaseError) -> User {
+///         guard let user = database.findUser(id: id) else {
+///             throw .recordNotFound(entity: "User", identifier: id)
+///         }
+///         return user
+///     }
+///
+///     func updateUser(_ user: User) throws(DatabaseError) {
+///         guard hasValidPermissions(for: user) else {
+///             throw .operationFailed(context: "Updating user profile")
+///         }
+///         // Update logic
+///     }
+/// }
+/// ```
 public enum DatabaseError: Throwable {
    /// The database connection failed.
+   ///
+   /// # Example
+   /// ```swift
+   /// struct AuthenticationService {
+   ///     func authenticate() throws(DatabaseError) {
+   ///         guard let connection = attemptDatabaseConnection() else {
+   ///             throw .connectionFailed
+   ///         }
+   ///         // Proceed with authentication
+   ///     }
+   /// }
+   /// ```
    case connectionFailed
 
    /// The database query failed to execute.
+   ///
+   /// # Example
+   /// ```swift
+   /// struct AnalyticsRepository {
+   ///     func generateReport(for period: DateInterval) throws(DatabaseError) -> Report {
+   ///         guard period.duration <= maximumReportPeriod else {
+   ///             throw .operationFailed(context: "Generating analytics report")
+   ///         }
+   ///         // Report generation logic
+   ///     }
+   /// }
+   /// ```
    /// - Parameters:
    ///   - context: A description of the operation or entity being queried.
    case operationFailed(context: String)
 
    /// A requested record was not found in the database.
+   ///
+   /// # Example
+   /// ```swift
+   /// struct ProductInventory {
+   ///     func fetchProduct(sku: String) throws(DatabaseError) -> Product {
+   ///         guard let product = database.findProduct(bySKU: sku) else {
+   ///             throw .recordNotFound(entity: "Product", identifier: sku)
+   ///         }
+   ///         return product
+   ///     }
+   /// }
+   /// ```
    /// - Parameters:
    ///   - entity: The name of the entity or record type.
    ///   - identifier: A unique identifier for the missing entity.
    case recordNotFound(entity: String, identifier: String?)
 
    /// Generic error message if the existing cases don't provide the required details.
+   ///
+   /// # Example
+   /// ```swift
+   /// struct DataMigrationService {
+   ///     func migrate() throws(DatabaseError) {
+   ///         guard canPerformMigration() else {
+   ///             throw .generic(userFriendlyMessage: "Migration cannot be performed")
+   ///         }
+   ///         // Migration logic
+   ///     }
+   /// }
+   /// ```
    case generic(userFriendlyMessage: String)
 
    /// A user-friendly error message suitable for display to end users.
@@ -25,20 +106,20 @@ public enum DatabaseError: Throwable {
       case .connectionFailed:
          return String(
             localized: "BuiltInErrors.DatabaseError.connectionFailed",
-            defaultValue: "Failed to connect to the database. Please try again later.",
+            defaultValue: "Unable to establish a connection to the database. Check your network settings and try again.",
             bundle: .module
          )
       case .operationFailed(let context):
          return String(
             localized: "BuiltInErrors.DatabaseError.operationFailed",
-            defaultValue: "An error occurred while performing the operation: \(context). Please try again.",
+            defaultValue: "The database operation for \(context) could not be completed. Please retry the action.",
             bundle: .module
          )
       case .recordNotFound(let entity, let identifier):
-         let idMessage = identifier.map { " Identifier: \($0)." } ?? ""
+         let idMessage = identifier.map { " with ID \($0)" } ?? ""
          return String(
             localized: "BuiltInErrors.DatabaseError.recordNotFound",
-            defaultValue: "The \(entity) record could not be found.\(idMessage) Please check and try again.",
+            defaultValue: "The \(entity) record\(idMessage) was not found in the database. Verify the details and try again.",
             bundle: .module
          )
       case .generic(let userFriendlyMessage):

Sources/ErrorKit/BuiltInErrors/FileError.swift

@@ -1,17 +1,98 @@
 import Foundation
 
 /// Represents errors that occur during file operations.
+///
+/// # Examples of Use
+///
+/// ## Handling File Retrieval
+/// ```swift
+/// struct DocumentManager {
+///     func loadDocument(named name: String) throws(FileError) -> Document {
+///         guard let fileURL = findFile(named: name) else {
+///             throw .fileNotFound(fileName: name)
+///         }
+///         // Document loading logic
+///     }
+/// }
+/// ```
+///
+/// ## Managing File Operations
+/// ```swift
+/// struct FileProcessor {
+///     func processFile(at path: String) throws(FileError) {
+///         guard canWrite(to: path) else {
+///             throw .writeFailed(fileName: path)
+///         }
+///         // File processing logic
+///     }
+///
+///     func readConfiguration() throws(FileError) -> Configuration {
+///         guard let data = attemptFileRead() else {
+///             throw .readFailed(fileName: "config.json")
+///         }
+///         // Configuration parsing logic
+///     }
+/// }
+/// ```
 public enum FileError: Throwable {
    /// The file could not be found.
+   ///
+   /// # Example
+   /// ```swift
+   /// struct AssetManager {
+   ///     func loadImage(named name: String) throws(FileError) -> Image {
+   ///         guard let imagePath = searchForImage(name) else {
+   ///             throw .fileNotFound(fileName: name)
+   ///         }
+   ///         // Image loading logic
+   ///     }
+   /// }
+   /// ```
    case fileNotFound(fileName: String)
 
    /// There was an issue reading the file.
+   ///
+   /// # Example
+   /// ```swift
+   /// struct LogReader {
+   ///     func readLatestLog() throws(FileError) -> String {
+   ///         guard let logContents = attemptFileRead() else {
+   ///             throw .readFailed(fileName: "application.log")
+   ///         }
+   ///         return logContents
+   ///     }
+   /// }
+   /// ```
    case readFailed(fileName: String)
 
    /// There was an issue writing to the file.
+   ///
+   /// # Example
+   /// ```swift
+   /// struct DataBackup {
+   ///     func backup(data: Data) throws(FileError) {
+   ///         guard canWriteToBackupLocation() else {
+   ///             throw .writeFailed(fileName: "backup.dat")
+   ///         }
+   ///         // Backup writing logic
+   ///     }
+   /// }
+   /// ```
    case writeFailed(fileName: String)
 
    /// Generic error message if the existing cases don't provide the required details.
+   ///
+   /// # Example
+   /// ```swift
+   /// struct FileIntegrityChecker {
+   ///     func validateFile() throws(FileError) {
+   ///         guard passes(integrityCheck) else {
+   ///             throw .generic(userFriendlyMessage: "File integrity compromised")
+   ///         }
+   ///         // Validation logic
+   ///     }
+   /// }
+   /// ```
    case generic(userFriendlyMessage: String)
 
    /// A user-friendly error message suitable for display to end users.
@@ -20,19 +101,19 @@ public enum FileError: Throwable {
       case .fileNotFound(let fileName):
          return String(
             localized: "BuiltInErrors.FileError.fileNotFound",
-            defaultValue: "The file \(fileName) could not be found. Please check the file path.",
+            defaultValue: "The file \(fileName) could not be located. Please verify the file path and try again.",
             bundle: .module
          )
       case .readFailed(let fileName):
          return String(
             localized: "BuiltInErrors.FileError.readError",
-            defaultValue: "There was an issue reading the file \(fileName). Please try again.",
+            defaultValue: "An error occurred while attempting to read the file \(fileName). Please check file permissions and try again.",
             bundle: .module
          )
       case .writeFailed(let fileName):
          return String(
             localized: "BuiltInErrors.FileError.writeError",
-            defaultValue: "There was an issue writing to the file \(fileName). Please try again.",
+            defaultValue: "Unable to write to the file \(fileName). Ensure you have the necessary permissions and try again.",
             bundle: .module
          )
       case .generic(let userFriendlyMessage):

Sources/ErrorKit/BuiltInErrors/GenericError.swift

@@ -0,0 +1,59 @@
+import Foundation
+
+/// Represents a generic error with a custom user-friendly message.
+/// Use this when the built-in error types don't match your specific error case
+/// or when you need a simple way to throw custom error messages.
+///
+/// # Examples of Use
+///
+/// ## Custom Business Logic Validation
+/// ```swift
+/// struct BusinessRuleValidator {
+///     func validateComplexRule(data: BusinessData) throws(GenericError) {
+///         guard meetsCustomCriteria(data) else {
+///             throw GenericError(
+///                 userFriendlyMessage: String(localized: "The business data doesn't meet required criteria")
+///             )
+///         }
+///         // Continue with business logic
+///     }
+/// }
+/// ```
+///
+/// ## Application-Specific Errors
+/// ```swift
+/// struct CustomProcessor {
+///     func processSpecialCase() throws(GenericError) {
+///         guard canHandleSpecialCase() else {
+///             throw GenericError(
+///                 userFriendlyMessage: String(localized: "Unable to process this special case")
+///             )
+///         }
+///         // Special case handling
+///     }
+/// }
+/// ```
+public struct GenericError: Throwable {
+   /// A user-friendly message describing the error.
+   public let userFriendlyMessage: String
+
+   /// Creates a new generic error with a custom user-friendly message.
+   ///
+   /// # Example
+   /// ```swift
+   /// struct CustomValidator {
+   ///     func validateSpecialRequirement() throws(GenericError) {
+   ///         guard meetsRequirement() else {
+   ///             throw GenericError(
+   ///                 userFriendlyMessage: String(localized: "The requirement was not met. Please try again.")
+   ///             )
+   ///         }
+   ///         // Validation logic
+   ///     }
+   /// }
+   /// ```
+   /// - Parameter userFriendlyMessage: A clear, actionable message that will be shown to the user.
+   public init(userFriendlyMessage: String) {
+      self.userFriendlyMessage = userFriendlyMessage
+   }
+}