Common task pages

Sources/Documentation.docc/CommonTasks.md

@@ -1,16 +0,0 @@
-# Common Tasks
-
-Code snippet that covers the most common tasks. Feel free to copy and paste them to your next great project.
-
-@Metadata {
-    @PageImage(purpose: card, source: "common-tasks-card"))
-    @PageColor(blue)
-}
-
-## Overview
-
-<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
-
-### Section header
-
-<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->

Sources/Documentation.docc/CommonTasks/CommonTasks.md

@@ -0,0 +1,116 @@
+# Common Tasks
+
+Code snippet that covers the most common tasks. Feel free to copy and paste them to your next great project.
+
+@Metadata {
+    @PageImage(purpose: card, source: "common-tasks-card"))
+    @PageColor(blue)
+}
+
+## 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).
+
+For common tasks of a specific part of Kingfisher, check the documentation below as well:
+
+- <doc:CommonTasks_>
+
+
+
+## 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.
+
+### Setting image with a `URL`
+
+```swift
+let url = URL(string: "https://example.com/image.jpg")
+imageView.kf.setImage(with: url)
+```
+
+This simple code does these things:
+
+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.
+
+
+### Showing a placeholder
+
+```swift
+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`.
+
+> You could also use a customized `UIView` or `NSView` as placeholder, by conforming it to `Placeholder`:
+>
+> ```swift
+> class MyView: UIView { /* Your implementation of view */ }
+>
+> extension MyView: Placeholder { /* Just leave it empty */}
+> 
+> imageView.kf.setImage(with: url, placeholder: MyView())
+> ```
+>
+> The `MyView` instance will be added to / removed from the `imageView` as needed.
+
+### Showing a loading indicator while downloading
+
+```swift
+imageView.kf.indicatorType = .activity
+imageView.kf.setImage(with: url)
+```
+
+Show a `UIActivityIndicatorView` in center of image view while downloading.
+
+### Fading in downloaded image
+
+```swift
+imageView.kf.setImage(with: url, options: [.transition(.fade(0.2))])
+```
+
+### Completion handler
+
+```swift
+imageView.kf.setImage(with: url) { result in
+    // `result` is either a `.success(RetrieveImageResult)` or a `.failure(KingfisherError)`
+    switch result {
+    case .success(let value):
+        // The image was set to image view:
+        print(value.image)
+
+        // From where the image was retrieved:
+        // - .none - Just downloaded.
+        // - .memory - Got from memory cache.
+        // - .disk - Got from disk cache.
+        print(value.cacheType)
+
+        // The source object which contains information like `url`.
+        print(value.source)
+
+    case .failure(let error):
+        print(error) // The error happens
+    }
+}
+```
+
+### 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:
+
+```swift
+KingfisherManager.shared.retrieveImage(with: url) { result in 
+    // Do something with `result`
+}
+```

Sources/Documentation.docc/CommonTasks/CommonTasks_Cache.md

@@ -0,0 +1,180 @@
+# CommonTasks - Cache
+
+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.
+
+### 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.
+
+```swift
+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.
+
+#### Check whether an image in the cache
+
+```swift
+let cache = ImageCache.default
+let cached = cache.isCached(forKey: cacheKey)
+
+// To know where the cached image is:
+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:
+
+```swift
+let processor = RoundCornerImageProcessor(cornerRadius: 20)
+imageView.kf.setImage(with: url, options: [.processor(processor)])
+
+// Later
+cache.isCached(forKey: cacheKey, processorIdentifier: processor.identifier)
+```
+
+#### Get an image from cache
+
+```swift
+cache.retrieveImage(forKey: "cacheKey") { result in
+    switch result {
+    case .success(let value):
+        print(value.cacheType)
+
+        // If the `cacheType is `.none`, `image` will be `nil`.
+        print(value.image)
+
+    case .failure(let error):
+        print(error)
+    }
+}
+```
+
+#### Set limit for cache
+
+For memory storage, you can set its `totalCostLimit` and `countLimit`:
+
+```swift
+// Limit memory cache size to 300 MB.
+cache.memoryStorage.config.totalCostLimit = 300 * 1024 * 1024
+
+// Limit memory cache to hold 150 images at most. 
+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.
+
+For disk storage, you can set `sizeLimit` for space on the file system.
+
+```swift
+// Limit disk cache size to 1 GB.
+cache.diskStorage.config.sizeLimit =  = 1000 * 1024 * 1024
+```
+
+#### Set 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:
+
+```swift
+// Memory image expires after 10 minutes.
+cache.memoryStorage.config.expiration = .seconds(600)
+
+// 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:
+
+```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:
+
+```swift
+// Check memory clean up every 30 seconds.
+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:
+
+```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:
+
+```swift
+let data: Data = //...
+let image: UIImage = //...
+cache.store(image, original: data, forKey: cacheKey)
+```
+
+#### Remove images from cache manually
+
+Kingfisher manages its cache automatically. But you still can manually remove a certain image from cache:
+
+```swift
+cache.default.removeImage(forKey: cacheKey)
+```
+
+Or, with more control:
+
+```swift
+cache.removeImage(
+    forKey: cacheKey,
+    processorIdentifier: processor.identifier,
+    fromMemory: false,
+    fromDisk: true)
+{
+    print("Removed!")
+}
+```
+
+#### Clear the cache
+
+```swift
+// Remove all.
+cache.clearMemoryCache()
+cache.clearDiskCache { print("Done") }
+
+// Remove only expired.
+cache.cleanExpiredMemoryCache()
+cache.cleanExpiredDiskCache { print("Done") }
+```
+
+#### Report the disk storage size
+
+```swift
+ImageCache.default.calculateDiskStorageSize { result in
+    switch result {
+    case .success(let size):
+        print("Disk cache size: \(Double(size) / 1024 / 1024) MB")
+    case .failure(let error):
+        print(error)
+    }
+}
+```
+
+#### Create your own cache and use it
+
+```swift
+// The `name` parameter is used to identify the disk cache bound to the `ImageCache`.
+let cache = ImageCache(name: "my-own-cache")
+imageView.kf.setImage(with: url, options: [.targetCache(cache)])
+```
+
+