Rename and add doc

Sources/General/KingfisherError.swift

@@ -171,14 +171,18 @@ public enum KingfisherError: Error {
         ///           happens.
         /// - error: The `Error` if an issue happens during image setting task. `nil` if the task finishes without
         ///          problem.
-        /// - source: The original source value of the taks.
+        /// - source: The original source value of the task.
         case notCurrentSourceTask(result: RetrieveImageResult?, error: Error?, source: Source)
 
         /// An error happens during getting data from an `ImageDataProvider`. Code 5003.
         case dataProviderError(provider: ImageDataProvider, error: Error)
 
+        /// No more alternative `Source` can be used in current loading process. It means that the
+        /// `.alternativeSources` are used and Kingfisher tried to recovery from the original error, but still
+        /// fails for all the given alternative sources. The associated value holds all the errors encountered during
+        /// the load process, including the original source loading error and all the alternative sources errors.
         /// Code 5004.
-        case alternativeSourcesFailed([PropagationError])
+        case alternativeSourcesExhausted([PropagationError])
     }
 
     // MARK: Member Cases
@@ -391,7 +395,7 @@ extension KingfisherError.ImageSettingErrorReason {
             }
         case .dataProviderError(let provider, let error):
             return "Image data provider fails to provide data. Provider: \(provider), error: \(error)"
-        case .alternativeSourcesFailed(let errors):
+        case .alternativeSourcesExhausted(let errors):
             return "Image setting from alternaive sources failed: \(errors)"
         }
     }
@@ -401,7 +405,7 @@ extension KingfisherError.ImageSettingErrorReason {
         case .emptySource: return 5001
         case .notCurrentSourceTask: return 5002
         case .dataProviderError: return 5003
-        case .alternativeSourcesFailed: return 5004
+        case .alternativeSourcesExhausted: return 5004
         }
     }
 }

Sources/General/KingfisherManager.swift

@@ -43,12 +43,18 @@ public struct RetrieveImageResult {
     /// If the image is just downloaded from network, `.none` will be returned.
     public let cacheType: CacheType
 
-    /// The `Source` from which the retrieve task begins.
+    /// The `Source` which this result is related to. This indicated where the `image` of `self` is referring.
     public let source: Source
 
+    /// The original `Source` from which the retrieve task begins. It can be different from the `source` property.
+    /// When an alternative source loading happened, the `source` will be the replacing loading target, while the
+    /// `originalSource` will be kept as the initial `source` which issued the image loading process.
     public let originalSource: Source
 }
 
+/// The downloading task updated block type. The parameter `newTask` is the updated new task of image setting process.
+/// It is a `nil` if the image loading does not require an image downloading process. If an image downloading is issued,
+/// this value will contain the actual `DownloadTask` for you to keep and cancel it later if you need.
 public typealias DownloadTaskUpdatedBlock = ((_ newTask: DownloadTask?) -> Void)
 
 /// Main manager class of Kingfisher. It connects Kingfisher downloader and cache,
@@ -102,16 +108,19 @@ public class KingfisherManager {
         processingQueue = .dispatch(DispatchQueue(label: processQueueName))
     }
 
-    // Mark: Getting Images
+    // MARK: - Getting Images
 
     /// Gets an image from a given resource.
-    ///
     /// - Parameters:
     ///   - resource: The `Resource` object defines data information like key or URL.
     ///   - options: Options to use when creating the animated image.
     ///   - progressBlock: Called when the image downloading progress gets updated. If the response does not contain an
     ///                    `expectedContentLength`, this block will not be called. `progressBlock` is always called in
     ///                    main queue.
+    ///   - downloadTaskUpdated: Called when a new image downloading task is created for current image retrieving. This
+    ///                          usually happens when an alternative source is used to replace the original (failed)
+    ///                          task. You can update your reference of `DownloadTask` if you want to manually `cancel`
+    ///                          the new task.
     ///   - completionHandler: Called when the image retrieved and set finished. This completion handler will be invoked
     ///                        from the `options.callbackQueue`. If not specified, the main queue will be used.
     /// - Returns: A task represents the image downloading. If there is a download task starts for `.network` resource,
@@ -121,7 +130,6 @@ public class KingfisherManager {
     ///    This method will first check whether the requested `resource` is already in cache or not. If cached,
     ///    it returns `nil` and invoke the `completionHandler` after the cached image retrieved. Otherwise, it
     ///    will download the `resource`, store it in cache, then call `completionHandler`.
-    ///
     @discardableResult
     public func retrieveImage(
         with resource: Resource,
@@ -148,6 +156,10 @@ public class KingfisherManager {
     ///   - progressBlock: Called when the image downloading progress gets updated. If the response does not contain an
     ///                    `expectedContentLength`, this block will not be called. `progressBlock` is always called in
     ///                    main queue.
+    ///   - downloadTaskUpdated: Called when a new image downloading task is created for current image retrieving. This
+    ///                          usually happens when an alternative source is used to replace the original (failed)
+    ///                          task. You can update your reference of `DownloadTask` if you want to manually `cancel`
+    ///                          the new task.
     ///   - completionHandler: Called when the image retrieved and set finished. This completion handler will be invoked
     ///                        from the `options.callbackQueue`. If not specified, the main queue will be used.
     /// - Returns: A task represents the image downloading. If there is a download task starts for `.network` resource,
@@ -208,7 +220,7 @@ public class KingfisherManager {
                     } else {
                         context.appendError(error, to: currentSource)
                         let finalError = KingfisherError.imageSettingError(
-                            reason: .alternativeSourcesFailed(context.propagationErrors)
+                            reason: .alternativeSourcesExhausted(context.propagationErrors)
                         )
                         completionHandler?(.failure(finalError))
                     }

Sources/General/KingfisherOptionsInfo.swift

@@ -134,7 +134,7 @@ public enum KingfisherOptionsInfoItem {
     case requestModifier(ImageDownloadRequestModifier)
     
     /// The `ImageDownloadRedirectHandler` contained will be used to change the request before redirection.
-    /// This is the posibility you can modify the image download request during redirect. You can modify the request for
+    /// This is the possibility you can modify the image download request during redirect. You can modify the request for
     /// some customizing purpose, such as adding auth token to the header, do basic HTTP auth or something like url
     /// mapping.
     /// The original redirection request will be sent without any modification by default.
@@ -230,6 +230,15 @@ public enum KingfisherOptionsInfoItem {
     /// Enable progressive image loading, Kingfisher will use the `ImageProgressive` of
     case progressiveJPEG(ImageProgressive)
 
+    /// The alternative sources will be used when the original input `Source` fails. The `Source`s in the associated
+    /// array will be used to start a new image loading task if the previous task fails due to an error. The image
+    /// source loading process will stop as soon as a source is loaded successfully. If all `[Source]`s are used but
+    /// the loading is still failing, an `imageSettingError` with `alternativeSourcesExhausted` as its reason will be
+    /// thrown out.
+    ///
+    /// This option is useful if you want to implement a fallback solution for setting image.
+    ///
+    /// User cancellation will not trigger the alternative source loading.
     case alternativeSources([Source])
 }
 

Tests/KingfisherTests/KingfisherManagerTests.swift

@@ -774,7 +774,7 @@ class KingfisherManagerTests: XCTestCase {
                 return
             }
 
-            guard case .alternativeSourcesFailed(let errorInfo) = reason else {
+            guard case .alternativeSourcesExhausted(let errorInfo) = reason else {
                 XCTFail("The error reason should be alternativeSourcesFailed")
                 return
             }