feat: apply comments

Sources/Defaults/Defaults+iCloud.swift

@@ -72,7 +72,7 @@ final class iCloudSynchronizer {
 
  self.enqueue {
  self.recordTimestamp(forKey: key, timestamp: Self.timestamp, source: .local)
- await self.syncKey(key: key, .local)
+ await self.syncKey(key, source: .local)
  }
  }
 
@@ -125,7 +125,7 @@ final class iCloudSynchronizer {
  for key in keys {
  let latest = source ?? latestDataSource(forKey: key)
  self.enqueue {
- await self.syncKey(key: key, latest)
+ await self.syncKey(key, source: latest)
  }
  }
  }
@@ -154,7 +154,7 @@ final class iCloudSynchronizer {
  - Parameter key: The key to synchronize.
  - Parameter source: Sync key from which data source (remote or local).
  */
- private func syncKey(key: Defaults.Keys, _ source: Defaults.DataSource) async {
+ private func syncKey(_ key: Defaults.Keys, source: Defaults.DataSource) async {
  Self.logKeySyncStatus(key, source: source, syncStatus: .idle)
 
  switch source {
@@ -227,7 +227,7 @@ final class iCloudSynchronizer {
 
  The timestamp storage format varies across different source providers due to storage limitations.
  */
- private func timestamp(forKey key: Defaults.Keys, _ source: Defaults.DataSource) -> Date? {
+ private func timestamp(forKey key: Defaults.Keys, source: Defaults.DataSource) -> Date? {
  switch source {
  case .remote:
  guard
@@ -277,10 +277,10 @@ final class iCloudSynchronizer {
  */
  private func latestDataSource(forKey key: Defaults.Keys) -> Defaults.DataSource {
  // If the remote timestamp does not exist, use the local timestamp as the latest data source.
- guard let remoteTimestamp = self.timestamp(forKey: key, .remote) else {
+ guard let remoteTimestamp = self.timestamp(forKey: key, source: .remote) else {
  return .local
  }
- guard let localTimestamp = self.timestamp(forKey: key, .local) else {
+ guard let localTimestamp = self.timestamp(forKey: key, source: .local) else {
  return .remote
  }
 
@@ -306,14 +306,14 @@ extension iCloudSynchronizer {
  .store(in: &cancellables)
 
  // TODO: Replace it with async stream when Swift supports custom executors.
- #if os(iOS) || os(tvOS)
+ #if os(iOS) || os(tvOS) || os(visionOS)
  NotificationCenter.default
  .publisher(for: UIScene.willEnterForegroundNotification)
  #elseif os(watchOS)
  NotificationCenter.default
  .publisher(for: WKExtension.applicationWillEnterForegroundNotification)
  #endif
- #if os(iOS) || os(tvOS) || os(watchOS)
+ #if os(iOS) || os(tvOS) || os(watchOS) || os(visionOS)
  .sink { [weak self] notification in
  guard let self else {
  return
@@ -344,18 +344,18 @@ extension iCloudSynchronizer {
  }
 
  for key in self.keys where changedKeys.contains(key.name) {
- guard let remoteTimestamp = self.timestamp(forKey: key, .remote) else {
+ guard let remoteTimestamp = self.timestamp(forKey: key, source: .remote) else {
  continue
  }
  if
- let localTimestamp = self.timestamp(forKey: key, .local),
+ let localTimestamp = self.timestamp(forKey: key, source: .local),
  localTimestamp >= remoteTimestamp
  {
  continue
  }
 
  self.enqueue {
- await self.syncKey(key: key, .remote)
+ await self.syncKey(key, source: .remote)
  }
  }
  }
@@ -365,7 +365,7 @@ extension iCloudSynchronizer {
 `iCloudSynchronizer` logging related functions.
 */
 extension iCloudSynchronizer {
- @available(macOS 11, iOS 14, tvOS 14, watchOS 7, *)
+ @available(macOS 11, iOS 14, tvOS 14, watchOS 7, visionOS 1, *)
  private static let logger = Logger(OSLog.default)
 
  private static func logKeySyncStatus(_ key: Defaults.Keys, source: Defaults.DataSource, syncStatus: SyncStatus, value: Any? = nil) {
@@ -439,12 +439,13 @@ extension Defaults {
  /**
  Synchronize values with different devices over iCloud.
 
- There are four ways to initiate synchronization, each of which will create a task in `backgroundQueue`:
+ There are five ways to initiate synchronization, each of which will create a synchronization task in ``Defaults/iCloud/iCloud``:
 
  1. Using ``iCloud/add(_:)-5gffb``
  2. Utilizing ``iCloud/syncWithoutWaiting(_:source:)-9cpju``
  3. Observing UserDefaults for added ``Defaults/Defaults/Key`` using Key-Value Observation (KVO)
  4. Monitoring `NSUbiquitousKeyValueStore.didChangeExternallyNotification` for added ``Defaults/Defaults/Key``.
+ 5. Initializing ``Defaults/Defaults/Keys`` with parameter `iCloud: true`.
 
  > Tip: After initializing the task, we can call ``iCloud/sync()`` to ensure that all tasks in the backgroundQueue are completed.
 
@@ -458,7 +459,7 @@ extension Defaults {
  Task {
  let quality = Defaults.Key<Int>("quality", default: 0)
  Defaults.iCloud.add(quality)
- await Defaults.iCloud.sync() // Using sync to make sure all synchronization tasks are done.
+ await Defaults.iCloud.sync() // Optional step: only needed if you require everything to be synced before continuing.
  // Both `isUnicornMode` and `quality` are synced.
  }
  ```
@@ -470,7 +471,7 @@ extension Defaults {
  static var synchronizer = iCloudSynchronizer(remoteStorage: NSUbiquitousKeyValueStore.default)
 
  /**
- Lists the synced keys.
+ The synced keys.
  */
  public static var keys: Set<Defaults.Keys> { synchronizer.keys }
 
@@ -481,6 +482,7 @@ extension Defaults {
 
  /**
  Enable this if you want to debug the syncing status of keys.
+ Logs will be printed to the console in OSLog format.
 
  - Note: The log information will include details such as the key being synced, its corresponding value, and the status of the synchronization.
  */

Sources/Defaults/Defaults.swift

@@ -103,7 +103,7 @@ extension Defaults {
  Create a key.
 
  - Parameter name: The name must be ASCII, not start with `@`, and cannot contain a dot (`.`).
- - Parameter iCloud: Set `true` if you want automatic synchronization to iCloud.
+ - Parameter iCloud: Automatically synchronize the value with ``Defaults/Defaults/iCloud``.
 
  The `default` parameter should not be used if the `Value` type is an optional.
  */
@@ -148,6 +148,7 @@ extension Defaults {
  ```
 
  - Parameter name: The name must be ASCII, not start with `@`, and cannot contain a dot (`.`).
+ - Parameter iCloud: Automatically synchronize the value with ``Defaults/Defaults/iCloud``.
 
  - Note: This initializer will not set the default value in the actual `UserDefaults`. This should not matter much though. It's only really useful if you use legacy KVO bindings.
  */

Sources/Defaults/Utilities.swift

@@ -365,6 +365,7 @@ final class TaskQueue {
  }
 }
 
+// TODO: replace with Swift 6 native Atomics support.
 @propertyWrapper
 final class Atomic<Value> {
  private let lock: Lock = .make()