Merge pull request #2411 from onevcat/fix/issue-2403-swiftui-sync-loading-docs

Fix documentation for loadDiskFileSynchronously in SwiftUI components

Sources/General/KFOptionsSetter.swift

@@ -294,12 +294,16 @@ extension KFOptionSetter {
     ///
     /// By default, disk storage file loading operates in its own queue with asynchronous dispatch behavior. While this 
     /// provides better non-blocking disk loading performance, it can result in flickering when reloading an image
-    ///  from disk if the image view already has an image set.
+    /// from disk if the image view already has an image set.
     ///
     /// Enabling this option prevents flickering by performing all loading in the same queue (typically the UI queue if 
     /// you are using Kingfisher's extension methods to set an image). However, this may come at the cost of loading
     /// performance.
     ///
+    /// - Note: When using SwiftUI components (e.g., `KFImage`), this option is enabled by default to prevent 
+    /// flickering during view updates. This is essential for maintaining visual consistency in SwiftUI's declarative
+    /// environment. For UIKit/AppKit usage, the default remains `false` for optimal performance.
+    ///
     public func loadDiskFileSynchronously(_ enabled: Bool = true) -> Self {
         options.loadDiskFileSynchronously = enabled
         return self

Sources/SwiftUI/KFAnimatedImage.swift

@@ -28,6 +28,15 @@
 import SwiftUI
 import Combine
 
+/// Represents an animated image view in SwiftUI that manages its content using Kingfisher.
+///
+/// Similar to ``KFImage``, this view provides support for animated image formats like GIF.
+///
+/// - Important: Like ``KFImage``, `KFAnimatedImage` loads disk cached images synchronously by default 
+/// (`.loadDiskFileSynchronously()` is enabled). This prevents image flickering during SwiftUI view updates 
+/// but may impact performance when loading large animated images from disk. You can disable this behavior 
+/// by calling `.loadDiskFileSynchronously(false)` if you prefer better loading performance over visual consistency.
+///
 @available(iOS 14.0, macOS 11.0, tvOS 14.0, *)
 public struct KFAnimatedImage: KFImageProtocol {
     public typealias HoldingView = KFAnimatedImageViewRepresenter

Sources/SwiftUI/KFImage.swift

@@ -61,6 +61,11 @@ import Combine
 /// Here only very few are listed as demonstration. To check other available modifiers, see ``KFOptionSetter`` and its
 /// extension methods.
 ///
+/// - Important: `KFImage` loads disk cached images synchronously by default (`.loadDiskFileSynchronously()` is enabled).
+/// This prevents image flickering during SwiftUI view updates but may impact performance when loading large images from disk.
+/// You can disable this behavior by calling `.loadDiskFileSynchronously(false)` if you prefer better loading performance
+/// over visual consistency.
+///
 @available(iOS 14.0, macOS 11.0, tvOS 14.0, watchOS 7.0, *)
 public struct KFImage: KFImageProtocol {