Fix documentation for loadDiskFileSynchronously in SwiftUI components

This addresses issue #2403 by updating the documentation to accurately reflect
that SwiftUI components (KFImage and KFAnimatedImage) enable loadDiskFileSynchronously
by default. This default behavior is intentional to prevent image flickering during
SwiftUI view updates.

Changes:
- Updated loadDiskFileSynchronously documentation in KFOptionsSetter to clarify
  the different defaults between UIKit/AppKit and SwiftUI
- Added Important notes to KFImage and KFAnimatedImage documentation explaining
  the default synchronous loading behavior and its performance implications
- Provided guidance on how to disable this behavior if needed

Fixes #2403

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 {