Update doc

Sources/Documentation.docc/CommonTasks/CommonTasks.md

@@ -1,6 +1,7 @@
 # Common Tasks
 
-Code snippet that covers the most common tasks. Feel free to copy and paste them to your next great project.
+Below is a code snippet designed to address the most commonly encountered tasks. You are encouraged to freely integrate 
+this snippet into your upcoming projects.
 
 @Metadata {
     @PageImage(purpose: card, source: "common-tasks-card"))
@@ -9,31 +10,36 @@ Code snippet that covers the most common tasks. Feel free to copy and paste them
 
 ## Overview
 
-This documentation will describe some of the most common usage in general. The code snippet is based on iOS. 
-However, the similar code should also work for other platforms like macOS or tvOS, by replacing the corresponding class 
-(such as `UIImage` to `NSImage`, etc).
+This document provides a comprehensive guide to the most prevalent use cases. The included code snippet is tailored for 
+iOS development. Nevertheless, it can be adapted for other platforms, such as macOS or tvOS, with minimal modifications.
+This typically involves substituting specific classes (for instance, replacing `UIImage` with `NSImage`). 
 
-For common tasks of a specific part of Kingfisher, check the documentation below as well:
+To explore detailed instructions for specific components within the Kingfisher framework, please refer to the 
+subsequent documentation:
 
 #### Common Tasks for Main Components
 
-- <doc:CommonTasks_Cache>
-- <doc:CommonTasks_Downloader>
-- <doc:CommonTasks_Processor>
+@Links(visualStyle: list) {
+    - <doc:CommonTasks_Cache>
+    - <doc:CommonTasks_Downloader>
+    - <doc:CommonTasks_Processor>
+}
 
 #### Other Topics
 
-- <doc:Topic_Prefetch>
-- <doc:Topic_ImageDataProvider>
-- <doc:Topic_Indicator>
-- <doc:Topic_Retry>
-- <doc:Topic_LowDataMode> 
-- <doc:Topic_PerformanceTips>
+@Links(visualStyle: list) {
+    - <doc:Topic_Prefetch>
+    - <doc:Topic_ImageDataProvider>
+    - <doc:Topic_Indicator>
+    - <doc:Topic_Retry>
+    - <doc:Topic_LowDataMode> 
+    - <doc:Topic_PerformanceTips>
+}
 
 ## Most Common Tasks
 
-The view extension based APIs (for `UIImageView`, `NSImageView`, `UIButton` and `NSButton`) should be your first choice
-whenever possible. It keeps your code simple and elegant.
+The view extension-based APIs for `UIImageView`, `NSImageView`, `UIButton`, and `NSButton` are recommended as your 
+primary choice. They simplify and enhance the elegance of your code.
 
 ### Setting Image with a `URL`
 
@@ -42,18 +48,16 @@ let url = URL(string: "https://example.com/image.jpg")
 imageView.kf.setImage(with: url)
 ```
 
-This simple code does these things:
+This code performs the following actions:
 
-1. Checks whether an image is cached under the key `url.absoluteString`.
-2. If an image was found in the cache (either in memory or disk), sets it to `imageView.image`.
-3. If not, creates a request and download it from `url`.
-4. Converts the downloaded data to a `UIImage` object.
-5. Caches the image to memory and disk.
-6. Sets the `imageView.image` to display it.
-
-Later, when you call the `setImage` with the same url again, only step 1 and 2 will be performed, unless the cache is 
-purged.
+1. Verifies if an image is cached using the key `url.absoluteString`.
+2. Retrieves and assigns the image to `imageView.image` if found in cache (memory or disk).
+3. If absent, initiates a request and downloads from `url`.
+4. Transforms the downloaded data into a `UIImage`.
+5. Stores the image in both memory and disk caches.
+6. Updates `imageView.image` with the new image.
 
+Subsequent calls to `setImage` with the same URL will only execute steps 1 and 2, unless the cache has been cleared.
 
 ### Showing a Placeholder
 
@@ -62,19 +66,19 @@ let image = UIImage(named: "default_profile_icon")
 imageView.kf.setImage(with: url, placeholder: image)
 ```
 
-The `image` will show in the `imageView` while downloading from `url`.
+The `imageView` will display the `image` as the placeholder during its download from the `url`.
 
-> You could also use a customized `UIView` or `NSView` as placeholder, by conforming it to `Placeholder`:
->
+> You can also employ a custom `UIView` or `NSView` as a placeholder by making it conform to the `Placeholder` protocol:
+> 
 > ```swift
-> class MyView: UIView { /* Your implementation of view */ }
->
-> extension MyView: Placeholder { /* Just leave it empty */}
+> class MyView: UIView { /* Implementation of your view */ }
+> 
+> extension MyView: Placeholder { /* This can be left empty */ }
 > 
 > imageView.kf.setImage(with: url, placeholder: MyView())
 > ```
->
-> The `MyView` instance will be added to / removed from the `imageView` as needed.
+> 
+> The instance of `MyView` will be dynamically added to or removed from the `imageView` as required.
 
 ### Showing a Loading Indicator while Downloading
 
@@ -83,7 +87,7 @@ imageView.kf.indicatorType = .activity
 imageView.kf.setImage(with: url)
 ```
 
-Show a `UIActivityIndicatorView` in center of image view while downloading.
+This shows a `UIActivityIndicatorView` in center of image view while downloading.
 
 ### Fading in Downloaded Image
 
@@ -118,7 +122,9 @@ imageView.kf.setImage(with: url) { result in
 
 ### Getting an Image without Setting to UI
 
-Sometimes, you just want to get the image with Kingfisher instead of setting it to an image view. Use `KingfisherManager` for it:
+Occasionally, you might need to retrieve an image using Kingfisher without assigning it to an image view. In such
+cases, use ``KingfisherManager/retrieveImage(with:options:progressBlock:)-80fw1``
+
 
 ```swift
 KingfisherManager.shared.retrieveImage(with: url) { result in 

Sources/Documentation.docc/CommonTasks/CommonTasks_Cache.md

@@ -4,23 +4,26 @@ Common tasks related to the ``ImageCache`` in Kingfisher.
 
 ## Overview
 
-Kingfisher is using a hybrid `ImageCache` to manage the cached images, It consists of a memory storage and a disk
-storage, and provides high-level APIs to manipulate the cache system. If not specified, the `ImageCache.default` 
-instance will be used across in Kingfisher.
+Kingfisher employs a hybrid ``ImageCache`` for managing cached images, comprising both memory and disk storage. It 
+offers high-level APIs for cache management. Unless otherwise specified, the ``ImageCache.default`` instance is 
+used throughout Kingfisher.
 
 ### Using another cache key
 
-By default, URL will be used to create a string for the cache key. For network URLs, the `absoluteString` will be used. 
-In any case, you change the key by creating an `ImageResource` with your own key.
+By default, the URL is converted into a string to generate the cache key. For network URLs, `absoluteString` is 
+utilized. You can customize the key by creating an ``ImageResource`` object with a specified key.
 
 ```swift
-let resource = ImageResource(downloadURL: url, cacheKey: "my_cache_key")
+let resource = ImageResource(
+    downloadURL: url, 
+    cacheKey: "my_cache_key"
+)
 imageView.kf.setImage(with: resource)
 ```
 
-Kingfisher will use the `cacheKey` to search images in cache later. Use a different key for a different image.
+Kingfisher uses the `cacheKey` to locate images in the cache. Ensure you use a distinct key for each different image.
 
-#### Check whether an image in the cache
+#### Checking whether an image in the cache
 
 ```swift
 let cache = ImageCache.default
@@ -31,8 +34,8 @@ let cacheType = cache.imageCachedType(forKey: cacheKey)
 // `.memory`, `.disk` or `.none`.
 ```
 
-If you used a processor when you retrieve the image, the processed image will be stored in cache. In this case, also 
-pass the processor identifier:
+If a processor is applied when retrieving an image, the processed image will be cached. In this scenario, remember to 
+also include the processor identifier when manipulating the cache:
 
 ```swift
 let processor = RoundCornerImageProcessor(cornerRadius: 20)
@@ -42,7 +45,7 @@ imageView.kf.setImage(with: url, options: [.processor(processor)])
 cache.isCached(forKey: cacheKey, processorIdentifier: processor.identifier)
 ```
 
-#### Get an image from cache
+#### Getting an image from the cache
 
 ```swift
 cache.retrieveImage(forKey: "cacheKey") { result in
@@ -59,9 +62,9 @@ cache.retrieveImage(forKey: "cacheKey") { result in
 }
 ```
 
-#### Set limit for cache
+#### Set limit for the cache
 
-For memory storage, you can set its `totalCostLimit` and `countLimit`:
+For memory storage, you can set its ``MemoryStorage/Config/totalCostLimit`` and ``MemoryStorage/Config/countLimit``:
 
 ```swift
 // Limit memory cache size to 300 MB.
@@ -71,35 +74,39 @@ cache.memoryStorage.config.totalCostLimit = 300 * 1024 * 1024
 cache.memoryStorage.config.countLimit = 150
 ```
 
-By default, the `totalCostLimit` of memory cache is 25% of your total memory in the device, and there is no limit on image count.
+The default ``MemoryStorage/Config/totalCostLimit`` for the memory cache is set to 25% of the device's total memory, 
+with no limit on the ``MemoryStorage/Config/countLimit``.
 
-For disk storage, you can set `sizeLimit` for space on the file system.
+For disk storage, you have the option to set a ``DiskStorage/Config/sizeLimit`` to manage the space used on the file 
+system.
 
 ```swift
 // Limit disk cache size to 1 GB.
 cache.diskStorage.config.sizeLimit =  = 1000 * 1024 * 1024
 ```
 
-#### Set default expiration for cache
+#### Set the default expiration for cache
 
-Both memory storage and disk storage have default expiration setting. Images in memory storage will expire after 5 minutes from last accessed, while it is a week for images in disk storage. You can change this value by:
+Both memory and disk storage in Kingfisher have default expiration settings. Images in memory storage expire 5 minutes 
+after the last access, whereas images in disk storage expire after one week. These values can be modified as follows:
 
 ```swift
-// Memory image expires after 10 minutes.
+// Set memory image expires after 10 minutes.
 cache.memoryStorage.config.expiration = .seconds(600)
 
-// Disk image never expires.
+// Set disk image never expires.
 cache.diskStorage.config.expiration = .never
 ```
 
-If you want to override this expiration for a certain image when caching it, pass in with an option:
+To override this default expiration for a specific image when caching it, include an option as follows during image 
+setting:
 
 ```swift
 // This image will never expire in memory cache.
 imageView.kf.setImage(with: url, options: [.memoryCacheExpiration(.never)])
 ```
 
-The expired memory cache will be purged with a duration of 2 minutes. If you want it happens more frequently:
+The expired memory cache is purged every 2 minutes by default. To adjust this frequency:
 
 ```swift
 // Check memory clean up every 30 seconds.
@@ -108,14 +115,16 @@ cache.memoryStorage.config.cleanInterval = 30
 
 #### Store images to cache manually
 
-By default, view extension methods and `KingfisherManager` will store the retrieved image to cache automatically. But you can also store an image to cache yourself:
+By default, view extension methods and ``KingfisherManager`` automatically store retrieved images in the cache. 
+However, you can also manually store an image to the cache:
 
 ```swift
 let image: UIImage = //...
 cache.store(image, forKey: cacheKey)
 ```
 
-If you have the original data of that image, also pass it to `ImageCache`, it helps Kingfisher to determine in which format the image should be stored:
+If you possess the original data of the image, pass it along to ``ImageCache``. This assists Kingfisher in determining 
+the appropriate format for storing the image:
 
 ```swift
 let data: Data = //...
@@ -128,7 +137,7 @@ cache.store(image, original: data, forKey: cacheKey)
 Kingfisher manages its cache automatically. But you still can manually remove a certain image from cache:
 
 ```swift
-cache.default.removeImage(forKey: cacheKey)
+cache.removeImage(forKey: cacheKey)
 ```
 
 Or, with more control:
@@ -191,11 +200,14 @@ This makes your app to an "offline" mode.
 imageView.kf.setImage(with: url, options: [.onlyFromCache])
 ```
 
-If the image is not existing in the cache, a `.cacheError` with `.imageNotExisting` reason will be raised.
+If the image does not exist in the cache, an ``KingfisherError/CacheErrorReason/imageNotExisting(key:)`` error will be
+triggered.
 
-#### Waiting for cache finishing
+#### Waiting for cache to finish
 
-Storing images to disk cache is an asynchronous operation. However, it is not required to be done before we can set the image view and call the completion handler in view extension methods. In other words, the disk cache may not exist yet in the completion handler below:
+Storing images in the disk cache is asynchronous and doesn't need to be completed before setting the image view and 
+invoking the completion handler in view extension methods. This means that the disk cache might not be fully updated at
+the time the completion handler is executed, as shown below:
 
 ```swift
 imageView.kf.setImage(with: url) { _ in
@@ -209,7 +221,9 @@ imageView.kf.setImage(with: url) { _ in
 }
 ```
 
-This is not a problem for most use cases. However, if your logic depends on the existing of disk cache, pass `.waitForCache` as an option. Kingfisher will then wait until the disk cache finishes before calling the handler:
+For most scenarios, this asynchronous behavior isn't an issue. However, if your logic relies on the existence of the 
+disk cache, use the `.waitForCache` option. With this option, Kingfisher will delay the execution of the handler until 
+the disk cache operation is complete:
 
 ```swift
 imageView.kf.setImage(with: url, options: [.waitForCache]) { _ in
@@ -223,4 +237,5 @@ imageView.kf.setImage(with: url, options: [.waitForCache]) { _ in
 }
 ```
 
-This is only for disk image cache, which involves to async I/O. For the memory cache, everything goes synchronously, so the image should be always in the memory cache.
+This consideration applies specifically to disk image caching, which involves asynchronous I/O operations. In contrast,
+memory cache operations are synchronous, ensuring that the image is always available in the memory cache.

Sources/Documentation.docc/MigrationGuide.md

@@ -1,11 +1,18 @@
 # Migration Guide
 
-<!--@START_MENU_TOKEN@-->Summary<!--@END_MENU_TOKEN@-->
+How to migrate from an earlier version of Kingfisher to the latest one.
 
-## Overview
+## Overview 
 
-<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
+### Migrating from v7 to v8
 
-### Section header
 
-<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
+### Archived
+
+If you are still using an even earlier version, check the archived guide below and follow them to migrate to v7 first.
+
+@Links(visualStyle: list) {
+    - <doc:Migration-To-7>
+    - <doc:Migration-To-6>
+}
+

Sources/Documentation.docc/MigrationGuide/Migration-To-6.md

@@ -0,0 +1,29 @@
+# Migrating from v5 to v6
+
+Migrating Kingfisher from version 5 to version 6.
+
+## Overview
+
+Kingfisher 6.0 contains some breaking changes if you want to upgrade from the previous version. 
+
+Depending on your use cases of Kingfisher 5.x, it may take no effort or at most several minutes to fix errors and warnings after upgrading. If you are not using Kingfisher with SwiftUI, and have no warnings in your code related to Kingfisher, then you are already done and feel free to upgrade to the latest version. Otherwise, please read the sections below before performing the upgrade.
+
+### SwiftUI support
+
+Kingfisher started to support SwiftUI from [5.8.0](https://github.com/onevcat/Kingfisher/releases/tag/5.8.0). At that time, a new framework was added to handle all SwiftUI-related things. Search for `KingfisherSwiftUI` in your SwiftUI code, or check if there is a `Kingfisher/SwiftUI` entry in your Podfile. If there is, then you need to perform some change of the integrating way before continuing.
+
+In Kingfisher 6, to make the project structure simpler, as well as treat SwiftUI as the first citizen in the library, we combined the library for SwiftUI into the main Kingfisher target.
+
+That means, there is no `KingfisherSwiftUI` or `Kingfisher/SwiftUI` anymore. If you installed it through:
+
+- Carthage: Remove `KingfisherSwiftUI` from "Linked Frameworks and Libraries" and all "KingfisherSwiftUI.framework" related lines from the "copy-framework".
+- CocoaPods: Remove `pod 'Kingfisher/SwiftUI'` from your Podfile. To continue using Kingfisher, you still need to keep or add back `pod 'Kingfisher'` entry. Then, run `pod install` again.
+- Swift Package Manager: Since now there is only one framework, all the old "static" and "dynamic" variants are removed. We suggest a clean reinstallation for the new version. Check the [Installation Guide](https://github.com/onevcat/Kingfisher/wiki/Installation-Guide) for more.
+
+When it is done, you can now replace any `import KingfisherSwiftUI` with `import Kingfisher`.
+
+### Removing legacy deprecated code
+
+All deprecated types, methods and properties are removed from the code base. Before upgrading, please make sure there is no warnings left in your project which complain the using of deprecated code. All deprecated things have replacement and with the help of warning message, adapting to new code should be easy enough.
+
+If you are curious about what are exactly removed, check [these commits](https://github.com/onevcat/Kingfisher/pull/1525/files).

Sources/Documentation.docc/MigrationGuide/Migration-To-7.md

@@ -0,0 +1,37 @@
+# Migrating from v6 to v7
+
+Migrating Kingfisher from version 6 to version 7.
+
+## Overview
+
+Kingfisher 7.0 contains some breaking changes if you want to upgrade from the previous version. In this documentation, we will cover most of the noticeable API changes.
+
+### Deploy target
+
+The UIKit/AppKit part of Kingfisher now supports from:
+
+- iOS 12.0
+- macOS 10.14
+- tvOS 12.0
+- watchOS 5.0
+
+> We do not have proper simulator support or device of versions before those. So dropping any older versions give us a chance to make sure the project works properly on all supported versions. This also fixes a compiling issue when building with Xcode 13 with SPM.
+
+The SwiftUI part of Kingfisher now supports from 
+
+- iOS 14
+- macOS 11.0
+- tvOS 14.0
+- watchOS 7.0
+
+> On iOS 13, there is no `@StateObject` property wrapper, which makes it very tricky when loading data properly across difference view body evaluating. For a stable data model in Kingfisher's SwiftUI, we need to drop iOS 13 and all other platform versions from the same year.
+
+### Migration Steps
+
+The main breaking changes happens to the SwiftUI support. By following the steps you should be able to migrate to the new version.
+
+- Make sure you do not have any warning from Kingfisher. All previous deprecated methods and properties are removed in version 7. If you are still using some of the deprecated methods, follow the help message to fix them first before migrating.
+- The original ``KFImage`` initializers: `init(source:isLoaded:)` and `init(_:isLoaded:)` are removed. Or strictly speaking, the `isLoaded` parameter is removed. If you are not using the `isLoaded` binding before, the transition to the new initializer ``KFImage/init(source:)`` and ``KFImage/init(_:)`` is transparent.
+    - The `isLoaded` binding was a mis-use of binding and it did not do what is expected. If you need to get a state of loading of a ``KFImage``, change a `@State` yourself in the related ``KFImage`` lifecycle modifier: such as ``KFImage/onSuccess(_:)`` and ``KFImage/onFailure(_:)``.
+    - All of the `isLoaded` parameter are also removed from the chain-able ``KF`` shorthand.
+- If you are using ``KFImage/loadImmediately(_:)`` to get workaround of [#1660](https://github.com/onevcat/Kingfisher/issues/1660), it is not necessary in the new version anymore. You will have a warning and please just remove it.