onevcat 2 лет назад
Родитель
Сommit
b83307f7c2

+ 30 - 18
Sources/Documentation.docc/CommonTasks/CommonTasks_Downloader.md

@@ -7,9 +7,11 @@ Common tasks related to the ``ImageDownloader`` in Kingfisher.
 ``ImageDownloader`` wraps a `URLSession` for downloading an image from the Internet. Similar to ``ImageCache``, there
 is a ``ImageDownloader/default`` downloader for downloading tasks.
 
-### Downloading an image manually
+### Download an image manually
 
-Usually, you may use Kingfisher's view extension methods or `KingfisherManager` to retrieve an image. They will try to search in the cache first to prevent unnecessary download task. In some cases, if you only want to download a target image without caching it:
+Typically, you might use Kingfisher's view extension methods or ``KingfisherManager`` for image retrieval. These methods 
+prioritize searching the cache to avoid unnecessary downloads. If you need to download an image without caching it, 
+consider the following approach:
 
 ```swift
 let downloader = ImageDownloader.default
@@ -23,9 +25,10 @@ downloader.downloadImage(with: url) { result in
 }
 ```
 
-### Modify a Request Before Sending
+### Modify a request before sending
 
-When you have permission control for your image resource, you can modify the request by using a `.requestModifier`:
+When managing access to your image resources with permission controls, you can customize the request using a
+``KingfisherOptionsInfoItem/requestModifier(_:)``:
 
 ```swift
 let modifier = AnyModifier { request in
@@ -42,9 +45,10 @@ downloader.downloadImage(with: url, options: [.requestModifier(modifier)]) {
 imageView.kf.setImage(with: url, options: [.requestModifier(modifier)])
 ```
 
-### Async Request Modifier
+### Use async request modifier
 
-If you need to perform some asynchronous operation before modifying the request, create a type and conform to `AsyncImageDownloadRequestModifier`:
+If an asynchronous operation is required before modifying the request, create a type that conforms to 
+``AsyncImageDownloadRequestModifier``:
 
 ```swift
 class AsyncModifier: AsyncImageDownloadRequestModifier {
@@ -60,7 +64,11 @@ class AsyncModifier: AsyncImageDownloadRequestModifier {
 }
 ```
 
-Similar as above, you can use the `.requestModifier` to use this modifier. In this case, the `setImage(with:options:)` or `ImageDownloader.downloadImage(with:options:)` method will not return a `DownloadTask` anymore (since it does not start the download task immediately). Instead, you observe one from the `onDownloadTaskStarted` callback if you need a reference to the task:
+Similarly, use the ``KingfisherOptionsInfoItem/requestModifier(_:)`` to apply this modifier. In such scenarios, the
+``KingfisherWrapper/setImage(with:placeholder:options:progressBlock:completionHandler:)-2uid3`` or
+``ImageDownloader/downloadImage(with:options:completionHandler:)-5x6sa`` method will no longer return a ``DownloadTask``
+directly, as the download task isn't initiated instantly. To reference the task, monitor the
+``AsyncImageDownloadRequestModifier/onDownloadTaskStarted`` callback.
 
 ```swift
 let modifier = AsyncModifier()
@@ -72,9 +80,10 @@ modifier.onDownloadTaskStarted = { task in
 let nilTask = imageView.kf.setImage(with: url, options: [.requestModifier(modifier)])
 ```
 
-### Cancelling a Download Task
+### Cancel a download task
 
-If the downloading started, a `DownloadTask` will be returned. You can use it to cancel an on-going download task:
+Once the download has started, a ``DownloadTask`` will be created and returned. This can be used to cancel an ongoing 
+download task.
 
 ```swift
 let task = downloader.downloadImage(with: url) { result in
@@ -85,20 +94,22 @@ let task = downloader.downloadImage(with: url) { result in
 
 }
 
-// After for a while, before download task finishes.
+// After some time, but before the download task completes.
 task?.cancel()
 ```
 
-If the task already finished when you call `task?.cancel()`, nothing will happen.
+If you call ``DownloadTask/cancel()`` after the task has already finished, no action will be taken.
 
-Similar, the view extension methods also return `DownloadTask`. You can store and cancel it:
+Likewise, the view extension methods return a ``DownloadTask`` as well. This allows you to store the task and cancel it 
+if needed:
 
 ```swift
 let task = imageView.kf.set(with: url)
 task?.cancel()
 ```
 
-Or, you can call `cancelDownloadTask` on the image view to cancel the **current downloading task**:
+Alternatively, you can invoke ``KingfisherWrapper/cancelDownloadTask()`` on the image view to cancel the 
+**current downloading task**.
 
 ```swift
 let task1 = imageView.kf.set(with: url1)
@@ -111,7 +122,8 @@ imageView.kf.cancelDownloadTask()
 
 ### Authentication with `NSURLCredential`
 
-The `ImageDownloader` uses a default behavior (`.performDefaultHandling`) when receives a challenge from server. If you need to provide your own credentials, setup an `authenticationChallengeResponder`:
+The ``ImageDownloader`` defaults to `.performDefaultHandling` upon receiving a server challenge. To supply custom 
+credentials, configure an ``ImageDownloader/authenticationChallengeResponder``:
 
 ```swift
 // In ViewController
@@ -143,16 +155,16 @@ extension ViewController: AuthenticationChallengeResponsable {
 }
 ```
 
-### Download Timeout
+### Set customize timeout
 
-By default, the download timeout for a request is 15 seconds. To set it for the downloader:
+The default download timeout for a request is 15 seconds. To customize this for the downloader:
 
 ```swift
-// Set timeout to 1 minute.
+// Set the timeout to 1 minute.
 downloader.downloadTimeout = 60
 ```
 
-To define a timeout for a certain request, use a `.requestModifier`:
+For setting a timeout specific to a request, utilize a ``KingfisherOptionsInfoItem/requestModifier(_:):``:
 
 ```swift
 let modifier = AnyModifier { request in

+ 19 - 4
Sources/Documentation.docc/CommonTasks/CommonTasks_Processor.md

@@ -4,10 +4,11 @@ Common tasks related to the ``ImageProcessor`` in Kingfisher.
 
 ## Overview
 
-``ImageProcessor`` transforms an image (or data) to another image. You can provide a processor to ``ImageDownloader`` 
-to  apply it to the downloaded data. Then processed image will be sent to the image view and the cache.
+``ImageProcessor`` is used to transform an image (or data) into another image. By supplying a processor to 
+``KingfisherManager`` when setting the image, it can be applied to the downloaded data. The processed image will then 
+be sent to the image view and stored in the cache.
 
-### Use the Default Processor
+### Use the default processor
 
 ```swift
 // Just without anything
@@ -16,10 +17,24 @@ imageView.kf.setImage(with: url)
 imageView.kf.setImage(with: url, options: [.processor(DefaultImageProcessor.default)])
 ```
 
-> `DefaultImageProcessor` converts downloaded data to a corresponded image object. PNG, JPEG, and GIF are supported.
+> The ``DefaultImageProcessor`` converts downloaded data into a corresponding image object. 
+> It supports PNG, JPEG, and GIF formats.
 
 ### Built-in Processors
 
+@Row {
+    @Column(size: 2) {
+        ```swift
+        // Round corner
+        RoundCornerImageProcessor(cornerRadius: 20)
+        ```
+    }
+    
+    @Column {
+        ![A screenshot of the power picker user interface with four powers displayed – ice, fire, wind, and lightning](common-tasks-card)
+    }
+}
+
 ```swift
 // Round corner
 let processor = RoundCornerImageProcessor(cornerRadius: 20)