feat: Adding documentation comments.

Sources/ConfigurationClient/ConfigurationClient.swift

@@ -6,24 +6,57 @@ import Foundation
 import ShellClient
 
 public extension DependencyValues {
+
+  /// Interacts with the user's configuration.
   var configurationClient: ConfigurationClient {
     get { self[ConfigurationClient.self] }
     set { self[ConfigurationClient.self] = newValue }
   }
 }
 
+/// Represents actions that can be taken on user's configuration files.
+///
+///
 @DependencyClient
 public struct ConfigurationClient: Sendable {
+
+  /// Find the user's configuration, searches in the current directory and default
+  /// locations where configuration can be stored. An error is thrown if no configuration
+  /// is found.
   public var find: @Sendable () async throws -> File
+
+  /// Generate a configuration file for the user.
   public var generate: @Sendable (GenerateOptions) async throws -> String
+
+  /// Load a configuration file from the given file location. If the file is
+  /// not provided then we return an empty configuraion item.
   public var load: @Sendable (File?) async throws -> Configuration
+
+  /// Write the configuration to the given file, optionally forcing an overwrite of
+  /// the file.
+  ///
+  /// ## NOTE: This uses the `fileClient.write` under the hood, so if you need to control
+  ///          what happens during tests, then you can customize the behavior of the fileClient.
+  ///
   var write: @Sendable (File, Configuration, Bool) async throws -> Void
 
+  /// Find the user's configuration and load it.
   public func findAndLoad() async throws -> Configuration {
     let file = try? await find()
     return try await load(file)
   }
 
+  /// Write the configuration to the given file, optionally forcing an overwrite of
+  /// the file. If a file already exists and force is not supplied then we will create
+  /// a backup of the existing file.
+  ///
+  /// ## NOTE: This uses the `fileClient.write` under the hood, so if you need to control
+  ///          what happens during tests, then you can customize the behavior of the fileClient.
+  ///
+  /// - Parameters:
+  ///   - configuration: The configuration to save.
+  ///   - file: The file location and type to save.
+  ///   - force: Force overwritting if a file already exists.
   public func write(
     _ configuration: Configuration,
     to file: File,
@@ -60,15 +93,12 @@ extension ConfigurationClient: DependencyKey {
 
   public static func live(environment: [String: String]) -> Self {
     let liveClient = LiveConfigurationClient(environment: environment)
-    return .init {
-      try await liveClient.find()
-    } generate: {
-      try await liveClient.generate($0)
-    } load: { file in
-      try await liveClient.load(file: file)
-    } write: { file, configuration, force in
-      try await liveClient.write(configuration, to: file, force: force)
-    }
+    return .init(
+      find: { try await liveClient.find() },
+      generate: { try await liveClient.generate($0) },
+      load: { try await liveClient.load(file: $0) },
+      write: { try await liveClient.write($1, to: $0, force: $2) }
+    )
   }
 
   public static var liveValue: Self {
@@ -221,10 +251,12 @@ struct LiveConfigurationClient {
     to file: File,
     force: Bool
   ) async throws {
-    if !force {
-      guard !fileManager.fileExists(file.url) else {
-        throw ConfigurationError.fileExists(path: file.path)
-      }
+    let exists = fileManager.fileExists(file.url)
+
+    if !force, exists {
+      let backupUrl = file.url.appendingPathExtension(".back")
+      logger.warning("File exists, creating a backup of the existing file at: \(backupUrl.cleanFilePath)")
+      try await fileManager.copy(file.url, backupUrl)
     }
 
     let data: Data