Add docs

Demo/Demo/Kingfisher-Demo/SwiftUIViews/SwiftUIView.swift

@@ -32,10 +32,13 @@ struct SwiftUIView : View {
 
     @State private var index = 1
 
+    var url: URL {
+        URL(string: "https://raw.githubusercontent.com/onevcat/Kingfisher-TestImages/master/DemoAppImage/Loading/kingfisher-\(self.index).jpg")!
+    }
+
     var body: some View {
         VStack {
-            KFImage(URL(string: "https://raw.githubusercontent.com/onevcat/Kingfisher-TestImages" +
-                                "/master/DemoAppImage/Loading/kingfisher-\(self.index).jpg")!)
+            KFImage(url)
                 .onSuccess { r in
                     print("suc: \(r)")
                 }

Sources/General/KF.swift

@@ -46,14 +46,16 @@ public enum KF {
 
     /// Creates a builder for a given `Source`.
     /// - Parameter source: The `Source` object defines data information from network or a data provider.
-    /// - Returns: A `KF.Builder` for future configuration or image setting.
+    /// - Returns: A `KF.Builder` for future configuration. After configuring the builder, call `set(to:)`
+    ///            to start the image loading.
     public static func source(_ source: Source) -> KF.Builder {
         Builder(source: source)
     }
 
     /// Creates a builder for a given `Resource`.
     /// - Parameter resource: The `Resource` object defines data information like key or URL.
-    /// - Returns: A `KF.Builder` for future configuration or image setting.
+    /// - Returns: A `KF.Builder` for future configuration. After configuring the builder, call `set(to:)`
+    ///            to start the image loading.
     public static func resource(_ resource: Resource) -> KF.Builder {
         Builder(source: .network(resource))
     }
@@ -63,14 +65,16 @@ public enum KF {
     ///   - url: The URL where the image should be downloaded.
     ///   - cacheKey: The key used to store the downloaded image in cache.
     ///               If `nil`, the `absoluteString` of `url` is used as the cache key.
-    /// - Returns: A `KF.Builder` for future configuration or image setting.
+    /// - Returns: A `KF.Builder` for future configuration. After configuring the builder, call `set(to:)`
+    ///            to start the image loading.
     public static func url(_ url: URL, cacheKey: String? = nil) -> KF.Builder {
         Builder(source: .network(ImageResource(downloadURL: url, cacheKey: cacheKey)))
     }
 
     /// Creates a builder for a given `ImageDataProvider`.
     /// - Parameter provider: The `ImageDataProvider` object contains information about the data.
-    /// - Returns: A `KF.Builder` for future configuration or image setting.
+    /// - Returns: A `KF.Builder` for future configuration. After configuring the builder, call `set(to:)`
+    ///            to start the image loading.
     public static func dataProvider(_ provider: ImageDataProvider) -> KF.Builder {
         Builder(source: .provider(provider))
     }
@@ -79,7 +83,8 @@ public enum KF {
     /// - Parameters:
     ///   - data: The data object from which the image should be created.
     ///   - cacheKey: The key used to store the downloaded image in cache.
-    /// - Returns: A `KF.Builder` for future configuration or image setting.
+    /// - Returns: A `KF.Builder` for future configuration. After configuring the builder, call `set(to:)`
+    ///            to start the image loading.
     public static func data(_ data: Data, cacheKey: String) -> KF.Builder {
         Builder(source: .provider(RawImageDataProvider(data: data, cacheKey: cacheKey)))
     }

Sources/SwiftUI/ImageBinder.swift

@@ -33,7 +33,7 @@ extension KFImage {
 
     /// Represents a binder for `KFImage`. It takes responsibility as an `ObjectBinding` and performs
     /// image downloading and progress reporting based on `KingfisherManager`.
-    public class ImageBinder: ObservableObject {
+    class ImageBinder: ObservableObject {
 
         let source: Source?
         var options = KingfisherParsedOptionsInfo(KingfisherManager.shared.defaultOptions)
@@ -50,7 +50,8 @@ extension KFImage {
 
         @Published var image: KFCrossPlatformImage?
 
-        init(source: Source?, options: KingfisherOptionsInfo?, isLoaded: Binding<Bool>) {
+        @available(*, deprecated, message: "The `options` version is deprecated And will be removed soon.")
+        init(source: Source?, options: KingfisherOptionsInfo? = nil, isLoaded: Binding<Bool>) {
             self.source = source
             // The refreshing of `KFImage` would happen much more frequently then an `UIImageView`, even as a
             // "side-effect". To prevent unintended flickering, add `.loadDiskFileSynchronously` as a default.
@@ -65,8 +66,11 @@ extension KFImage {
 
         init(source: Source?, isLoaded: Binding<Bool>) {
             self.source = source
+            // The refreshing of `KFImage` would happen much more frequently then an `UIImageView`, even as a
+            // "side-effect". To prevent unintended flickering, add `.loadDiskFileSynchronously` as a default.
             self.options = KingfisherParsedOptionsInfo(
-                KingfisherManager.shared.defaultOptions + [.loadDiskFileSynchronously]
+                KingfisherManager.shared.defaultOptions +
+                [.loadDiskFileSynchronously]
             )
             self.isLoaded = isLoaded
             self.image = nil
@@ -122,7 +126,7 @@ extension KFImage {
         }
 
         /// Cancels the download task if it is in progress.
-        public func cancel() {
+        func cancel() {
             downloadTask?.cancel()
         }
     }

Sources/SwiftUI/KFImage.swift

@@ -46,7 +46,7 @@ extension Image {
 public struct KFImage: View {
 
     /// An image binder that manages loading and cancelling image related task.
-    @ObservedObject public private(set) var binder: ImageBinder
+    @ObservedObject private(set) var binder: ImageBinder
 
     // Acts as a placeholder when loading an image.
     var placeholder: AnyView?
@@ -57,8 +57,6 @@ public struct KFImage: View {
     // Configurations should be performed on the image.
     var configurations: [(Image) -> Image]
 
-    #warning("Deprecate this.")
-
     /// Creates a Kingfisher compatible image view to load image from the given `Source`.
     /// - Parameter source: The image `Source` defining where to load the target image.
     /// - Parameter options: The options should be applied when loading the image.
@@ -66,28 +64,51 @@ public struct KFImage: View {
     /// - Parameter isLoaded: Whether the image is loaded or not. This provides a way to inspect the internal loading
     ///                       state. `true` if the image is loaded successfully. Otherwise, `false`. Do not set the
     ///                       wrapped value from outside.
+    /// - Deprecated: Some options are not available in SwiftUI yet. Use `KFImage(source:isLoaded:)` to create a
+    ///               `KFImage` and configure the options through modifier instead. See methods of `KFOptionSetter`
+    ///               for more.
+    @available(*, deprecated, message: "Some options are not available in SwiftUI yet. Use `KFImage(source:isLoaded:)` to create a `KFImage` and configure the options through modifier instead.")
     public init(source: Source?, options: KingfisherOptionsInfo? = nil, isLoaded: Binding<Bool> = .constant(false)) {
         binder = ImageBinder(source: source, options: options, isLoaded: isLoaded)
         configurations = []
     }
 
-    #warning("Deprecate this.")
-    /// Creates a Kingfisher compatible image view to load image from the given `Source`.
+    /// Creates a Kingfisher compatible image view to load image from the given `URL`.
     /// - Parameter url: The image URL from where to load the target image.
     /// - Parameter options: The options should be applied when loading the image.
     ///                      Some UIKit related options (such as `ImageTransition.flip`) are not supported.
     /// - Parameter isLoaded: Whether the image is loaded or not. This provides a way to inspect the internal loading
     ///                       state. `true` if the image is loaded successfully. Otherwise, `false`. Do not set the
     ///                       wrapped value from outside.
+    /// - Deprecated: Some options are not available in SwiftUI yet. Use `KFImage(_:isLoaded:)` to create a
+    ///               `KFImage` and configure the options through modifier instead. See methods of `KFOptionSetter`
+    ///               for more.
+    @available(*, deprecated, message: "Some options are not available in SwiftUI yet. Use `KFImage(_:isLoaded:)` to create a `KFImage` and configure the options through modifier instead.")
     public init(_ url: URL?, options: KingfisherOptionsInfo? = nil, isLoaded: Binding<Bool> = .constant(false)) {
         self.init(source: url?.convertToSource(), options: options, isLoaded: isLoaded)
     }
 
+    /// Creates a Kingfisher compatible image view to load image from the given `Source`.
+    /// - Parameters:
+    ///   - source: The image `Source` defining where to load the target image.
+    ///   - isLoaded: Whether the image is loaded or not. This provides a way to inspect the internal loading
+    ///               state. `true` if the image is loaded successfully. Otherwise, `false`. Do not set the
+    ///               wrapped value from outside.
     public init(source: Source?, isLoaded: Binding<Bool> = .constant(false)) {
         binder = ImageBinder(source: source, isLoaded: isLoaded)
         configurations = []
     }
 
+    /// Creates a Kingfisher compatible image view to load image from the given `URL`.
+    /// - Parameters:
+    ///   - source: The image `Source` defining where to load the target image.
+    ///   - isLoaded: Whether the image is loaded or not. This provides a way to inspect the internal loading
+    ///               state. `true` if the image is loaded successfully. Otherwise, `false`. Do not set the
+    ///               wrapped value from outside.
+    public init(_ url: URL?, isLoaded: Binding<Bool> = .constant(false)) {
+        self.init(source: url?.convertToSource(), isLoaded: isLoaded)
+    }
+
     /// Declares the content and behavior of this view.
     public var body: some View {
         Group {

Sources/SwiftUI/KFImageOptions.swift

@@ -29,27 +29,58 @@ import SwiftUI
 // MARK: - KFImage creating.
 @available(iOS 13.0, OSX 10.15, tvOS 13.0, watchOS 6.0, *)
 extension KFImage {
+
+    /// Creates a `KFImage` for a given `Source`.
+    /// - Parameters:
+    ///   - source: The `Source` object defines data information from network or a data provider.
+    ///   - isLoaded: Whether the image is loaded or not. This provides a way to inspect the internal loading
+    ///               state. `true` if the image is loaded successfully. Otherwise, `false`. Do not set the
+    ///               wrapped value from outside.
+    /// - Returns: A `KFImage` for future configuration or embedding to a `SwiftUI.View`.
     public static func source(
-        _ source: Source, isLoaded: Binding<Bool> = .constant(false)
+        _ source: Source?, isLoaded: Binding<Bool> = .constant(false)
     ) -> KFImage
     {
         KFImage(source: source, isLoaded: isLoaded)
     }
 
+    /// Creates a `KFImage` for a given `Resource`.
+    /// - Parameters:
+    ///   - source: The `Resource` object defines data information like key or URL.
+    ///   - isLoaded: Whether the image is loaded or not. This provides a way to inspect the internal loading
+    ///               state. `true` if the image is loaded successfully. Otherwise, `false`. Do not set the
+    ///               wrapped value from outside.
+    /// - Returns: A `KFImage` for future configuration or embedding to a `SwiftUI.View`.
     public static func resource(
-        _ resource: Resource, isLoaded: Binding<Bool> = .constant(false)
+        _ resource: Resource?, isLoaded: Binding<Bool> = .constant(false)
     ) -> KFImage
     {
-        .source(.network(resource), isLoaded: isLoaded)
+        .source(resource?.convertToSource(), isLoaded: isLoaded)
     }
 
+    /// Creates a `KFImage` for a given `URL`.
+    /// - Parameters:
+    ///   - url: The URL where the image should be downloaded.
+    ///   - cacheKey: The key used to store the downloaded image in cache.
+    ///               If `nil`, the `absoluteString` of `url` is used as the cache key.
+    ///   - isLoaded: Whether the image is loaded or not. This provides a way to inspect the internal loading
+    ///               state. `true` if the image is loaded successfully. Otherwise, `false`. Do not set the
+    ///               wrapped value from outside.
+    /// - Returns: A `KFImage` for future configuration or embedding to a `SwiftUI.View`.
     public static func url(
-        _ url: URL, cacheKey: String? = nil, isLoaded: Binding<Bool> = .constant(false)
+        _ url: URL?, cacheKey: String? = nil, isLoaded: Binding<Bool> = .constant(false)
     ) -> KFImage
     {
-        source(.network(ImageResource(downloadURL: url, cacheKey: cacheKey)), isLoaded: isLoaded)
+        source(url?.convertToSource(), isLoaded: isLoaded)
     }
 
+    /// Creates a `KFImage` for a given `ImageDataProvider`.
+    /// - Parameters:
+    ///   - provider: The `ImageDataProvider` object contains information about the data.
+    ///   - isLoaded: Whether the image is loaded or not. This provides a way to inspect the internal loading
+    ///               state. `true` if the image is loaded successfully. Otherwise, `false`. Do not set the
+    ///               wrapped value from outside.
+    /// - Returns: A `KFImage` for future configuration or embedding to a `SwiftUI.View`.
     public static func dataProvider(
         _ provider: ImageDataProvider, isLoaded: Binding<Bool> = .constant(false)
     ) -> KFImage
@@ -57,6 +88,14 @@ extension KFImage {
         source(.provider(provider), isLoaded: isLoaded)
     }
 
+    /// Creates a builder for some given raw data and a cache key.
+    /// - Parameters:
+    ///   - data: The data object from which the image should be created.
+    ///   - cacheKey: The key used to store the downloaded image in cache.
+    ///   - isLoaded: Whether the image is loaded or not. This provides a way to inspect the internal loading
+    ///               state. `true` if the image is loaded successfully. Otherwise, `false`. Do not set the
+    ///               wrapped value from outside.
+    /// - Returns: A `KFImage` for future configuration or embedding to a `SwiftUI.View`.
     public static func data(
         _ data: Data, cacheKey: String, isLoaded: Binding<Bool> = .constant(false)
     ) -> KFImage
@@ -77,7 +116,6 @@ extension KFImage {
         return result
     }
 
-
     /// Sets cancelling the download task bound to `self` when the view disappearing.
     /// - Parameter flag: Whether cancel the task or not.
     /// - Returns: A `KFImage` view that cancels downloading task when disappears.