Update documentation for 0.12.0. (#482)

* Update getting started and readme.

* Rename requests.md.

* Tweaks.

* WIP.

* Correct reference.

* More docs fixes.

* Tweak.

* Update CHANGELOG.md.

* Docs.

* Docs.

* Remove sections.

* Add section on memory cache.

* Tweaks.

* Updates.

* Copy README-zh.

* Tweaks.

* Fix.

* Fix.

* Fix.

* Fixes.

CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## [0.12.0] - August 18, 2020
+
+- **Breaking**: `LoadRequest` and `GetRequest` have been replaced with `ImageRequest`:
+  - `ImageLoader.execute(LoadRequest)` -> `ImageLoader.enqueue(ImageRequest)`
+  - `ImageLoader.execute(GetRequest)` -> `ImageLoader.execute(ImageRequest)`
+  - `ImageRequest` implements `equals`/`hashCode`.
+- **Breaking**: `RequestResult` and `RequestDisposable` have been renamed:
+  - `RequestResult` -> `ImageResult`
+  - `RequestDisposable` -> `Disposable`
+- **Breaking**: [`SparseIntArraySet`](https://github.com/coil-kt/coil/blob/f52addd039f0195b66f93cb0f1cad59b0832f784/coil-base/src/main/java/coil/collection/SparseIntArraySet.kt) has been removed from the public API.
+- **Breaking**: `TransitionTarget` no longer implements `ViewTarget`.
+- **Breaking**: `ImageRequest.Listener.onSuccess`'s signature has changed to return an `ImageResult.Metadata` instead of just a `DataSource`.
+- **Breaking**: Remove support for `LoadRequest.aliasKeys`. This API is better handled with direct read/write access to the memory cache.
+
+---
+
+- **Important**: Values in the memory cache are no longer resolved synchronously (if called from the main thread).
+  - This change was also necessary to support executing `Interceptor`s on a background dispatcher.
+  - This change also moves more work off the main thread, improving performance.
+- **Important**: `Mappers` are now executed on a background dispatcher. As a side effect, automatic bitmap sampling is no longer **automatically** supported. To achieve the same effect, use the `MemoryCache.Key` of a previous request as the `placeholderMemoryCacheKey` of the subsequent request. [See here for an example](https://coil-kt.github.io/coil/recipes/#using-a-memory-cache-key-as-a-placeholder).
+  - The `placeholderMemoryCacheKey` API offers more freedom as you can "link" two image requests with different data (e.g. different URLs for small/large images).
+- **Important**: Coil's `ImageView` extension functions have been moved from the `coil.api` package to the `coil` package.
+  - Use find + replace to refactor `import coil.api.load` -> `import coil.load`. Unfortunately, it's not possible to use Kotlin's `ReplaceWith` functionality to replace imports.
+- **Important**: Use standard crossfade if drawables are not the same image.
+- **Important**: Prefer immutable bitmaps on API 24+.
+- **Important**: `MeasuredMapper` has been deprecated in favour of the new `Interceptor` interface. See [here](https://gist.github.com/colinrtwhite/90267704091467451e46b21b95154299) for an example of how to convert a `MeasuredMapper` into an `Interceptor`.
+  - `Interceptor` is a much less restrictive API that allows for a wider range of custom logic.
+- **Important**: `ImageRequest.data` is now not null. If you create an `ImageRequest` without setting its data it will return `NullRequestData` as its data.
+
+---
+
+- **New**: Add support for direct read/write access to an `ImageLoader`'s `MemoryCache`. See [the docs](https://coil-kt.github.io/coil/getting_started/#memory-cache) for more information.
+- **New**: Add support for `Interceptor`s. See [the docs](https://coil-kt.github.io/coil/image_pipeline/#interceptors) for more information. Coil's `Interceptor` design is heavily inspired by [OkHttp](https://github.com/square/okhttp)'s!
+- **New**: Add the ability to enable/disable bitmap pooling using `ImageLoader.Builder.bitmapPoolingEnabled`.
+  - Bitmap pooling is most effective on API 23 and below, but may still be benificial on API 24 and up (by eagerly calling `Bitmap.recycle`).
+- **New**: Support thread interruption while decoding.
+
+---
+
+- Fix parsing multiple segments in content-type header.
+- Rework bitmap reference counting to be more robust.
+- Fix WebP decoding on API < 19 devices.
+- Expose FetchResult and DecodeResult in the EventListener API.
+
+---
+
+- Compile with SDK 30.
+- Update Coroutines to 1.3.8.
+- Update OkHttp to 3.12.12.
+- Update Okio to 2.7.0.
+- Update AndroidX dependencies:
+    - `androidx.appcompat:appcompat-resources` -> 1.2.0
+    - `androidx.core:core-ktx` -> 1.3.1
+
 ## [0.11.0] - May 14, 2020
 
 - **Breaking**: **This version removes all existing deprecated functions.**

README-ko.md

@@ -16,7 +16,7 @@ Coil은: **Co**routine **I**mage **L**oader의 약자입니다.
 Coil은 `mavenCentral()`로 이용 가능합니다.
 
 ```kotlin
-implementation("io.coil-kt:coil:0.11.0")
+implementation("io.coil-kt:coil:0.12.0")
 ```
 
 ## 빠른 시작
@@ -52,8 +52,7 @@ imageView.load("https://www.example.com/image.jpg") {
 
 - AndroidX
 - Min SDK 14+
-- Compile SDK: 29+
-- Java 8+
+- [Java 8+](https://coil-kt.github.io/coil/getting_started/#java-8)
 
 ## R8 / Proguard
 

README-zh.md

@@ -16,7 +16,7 @@ Coil的首字母由来：取**Co**routine，**I**mage和**L**oader得来Coil。
 Coil允许使用`mavenCentral()`.
 
 ```kotlin
-implementation("io.coil-kt:coil:0.11.0")
+implementation("io.coil-kt:coil:0.12.0")
 ```
 
 ## 快速使用
@@ -46,43 +46,6 @@ imageView.load("https://www.example.com/image.jpg") {
 }
 ```
 
-#### 图片加载
-`imageView.load`使用单例`ImageLoader`来执行`LoadRequest`。您也可以通过以下方式获得单例。
-```kotlin
-val imageLoader = Coil.imageLoader(context)
-```
-
-您也可以通过依赖注入的方式创建您自己的`ImageLoader`：
-```kotlin
-val imageLoader = ImageLoader(context)
-```
-
-如果您不需要单例`ImageLoader`，只需要添加依赖：`io.coil-kt:coil-base`。
-
-
-#### 请求
-
-通过`LoadRequest`加载自定义标签:
-
-```kotlin
-val request = LoadRequest.Builder(context)
-    .data("https://www.example.com/image.jpg")
-    .target { drawable ->
-        // Handle the result.
-    }
-    .build()
-imageLoader.execute(request)
-```
-
-也可以通过`GetRequest`获得一个drawable对象：
-
-```kotlin
-val request = GetRequest.Builder(context)
-    .data("https://www.example.com/image.jpg")
-    .build()
-val drawable = imageLoader.execute(request).drawable
-```
-
 也可以查看Coli文档获得更多信息： [full documentation here](https://coil-kt.github.io/coil/getting_started/).
 
 ## 环境要求

README.md

@@ -16,7 +16,7 @@ Made with ❤️ at [Instacart](https://www.instacart.com). Translations: [한
 Coil is available on `mavenCentral()`.
 
 ```kotlin
-implementation("io.coil-kt:coil:0.11.0")
+implementation("io.coil-kt:coil:0.12.0")
 ```
 
 ## Quick Start
@@ -48,7 +48,7 @@ imageView.load("https://www.example.com/image.jpg") {
 
 #### Image Loaders
 
-`imageView.load` uses the singleton `ImageLoader` to execute a `LoadRequest`. The singleton `ImageLoader` can be accessed using:
+`imageView.load` uses the singleton `ImageLoader` to enqueue an `ImageRequest`. The singleton `ImageLoader` can be accessed using:
 
 ```kotlin
 val imageLoader = Coil.imageLoader(context)
@@ -64,22 +64,22 @@ If you do not want the singleton `ImageLoader`, depend on `io.coil-kt:coil-base`
 
 #### Requests
 
-To load an image into a custom target, execute a `LoadRequest`:
+To load an image into a custom target, `enqueue` an `ImageRequest`:
 
 ```kotlin
-val request = LoadRequest.Builder(context)
+val request = ImageRequest.Builder(context)
     .data("https://www.example.com/image.jpg")
     .target { drawable ->
         // Handle the result.
     }
     .build()
-imageLoader.execute(request)
+val disposable = imageLoader.enqueue(request)
 ```
 
-To get an image imperatively, execute a `GetRequest`:
+To load an image imperatively, `execute` an `ImageRequest`:
 
 ```kotlin
-val request = GetRequest.Builder(context)
+val request = ImageRequest.Builder(context)
     .data("https://www.example.com/image.jpg")
     .build()
 val drawable = imageLoader.execute(request).drawable

coil-base/src/androidTest/java/coil/request/DisposableTest.kt

@@ -47,7 +47,7 @@ class DisposableTest {
     }
 
     @Test
-    fun baseTargetRequestDisposable_dispose() = runBlockingTest {
+    fun baseTargetDisposable_dispose() = runBlockingTest {
         val request = ImageRequest.Builder(context)
             .data("$SCHEME_FILE:///$ASSET_FILE_PATH_ROOT/normal.jpg")
             .size(100, 100)
@@ -63,7 +63,7 @@ class DisposableTest {
     }
 
     @Test
-    fun baseTargetRequestDisposable_await() = runBlockingTest {
+    fun baseTargetDisposable_await() = runBlockingTest {
         val transformation = GateTransformation()
         var result: Drawable? = null
         val request = ImageRequest.Builder(context)
@@ -82,7 +82,7 @@ class DisposableTest {
     }
 
     @Test
-    fun viewTargetRequestDisposable_dispose() = runBlockingTest {
+    fun viewTargetDisposable_dispose() = runBlockingTest {
         val imageView = ImageView(context)
         val request = ImageRequest.Builder(context)
             .data("$SCHEME_FILE:///$ASSET_FILE_PATH_ROOT/normal.jpg")
@@ -100,7 +100,7 @@ class DisposableTest {
     }
 
     @Test
-    fun viewTargetRequestDisposable_await() = runBlockingTest {
+    fun viewTargetDisposable_await() = runBlockingTest {
         val transformation = GateTransformation()
         val imageView = ImageView(context)
         val request = ImageRequest.Builder(context)
@@ -120,7 +120,7 @@ class DisposableTest {
     }
 
     @Test
-    fun viewTargetRequestDisposable_restart() = runBlockingTest {
+    fun viewTargetDisposable_restart() = runBlockingTest {
         val transformation = GateTransformation()
         val imageView = ImageView(context)
         val request = ImageRequest.Builder(context)
@@ -150,7 +150,7 @@ class DisposableTest {
     }
 
     @Test
-    fun viewTargetRequestDisposable_replace() = runBlockingTest {
+    fun viewTargetDisposable_replace() = runBlockingTest {
         val imageView = ImageView(context)
 
         fun launchNewRequest(): Disposable {
@@ -177,7 +177,7 @@ class DisposableTest {
     }
 
     @Test
-    fun viewTargetRequestDisposable_clear() = runBlockingTest {
+    fun viewTargetDisposable_clear() = runBlockingTest {
         val imageView = ImageView(context)
         val request = ImageRequest.Builder(context)
             .data("$SCHEME_FILE:///$ASSET_FILE_PATH_ROOT/normal.jpg")

coil-base/src/main/java/coil/fetch/Fetcher.kt

@@ -6,7 +6,7 @@ import android.graphics.Bitmap
 import android.graphics.drawable.Drawable
 import coil.bitmap.BitmapPool
 import coil.decode.Options
-import coil.memory.StrongMemoryCache
+import coil.memory.MemoryCache
 import coil.size.Size
 import okio.BufferedSource
 
@@ -29,7 +29,7 @@ interface Fetcher<T : Any> {
     /**
      * Compute the memory cache key for [data].
      *
-     * Items with the same cache key will be treated as equivalent by the [StrongMemoryCache].
+     * Items with the same cache key will be treated as equivalent by the [MemoryCache].
      *
      * Returning null will prevent the result of [fetch] from being added to the memory cache.
      */

coil-base/src/main/java/coil/request/DefinedRequestOptions.kt

@@ -1,4 +1,5 @@
 @file:OptIn(ExperimentalCoilApi::class)
+@file:Suppress("unused")
 
 package coil.request
 

coil-base/src/main/java/coil/request/ImageRequest.kt

@@ -239,7 +239,7 @@ class ImageRequest private constructor(
     }
 
     /**
-     * A set of callbacks for a [ImageRequest].
+     * A set of callbacks for an [ImageRequest].
      */
     interface Listener {
 
@@ -249,12 +249,6 @@ class ImageRequest private constructor(
         @MainThread
         fun onStart(request: ImageRequest) {}
 
-        /**
-         * Called if the request completes successfully.
-         */
-        @MainThread
-        fun onSuccess(request: ImageRequest, metadata: ImageResult.Metadata) {}
-
         /**
          * Called if the request is cancelled.
          */
@@ -266,6 +260,12 @@ class ImageRequest private constructor(
          */
         @MainThread
         fun onError(request: ImageRequest, throwable: Throwable) {}
+
+        /**
+         * Called if the request completes successfully.
+         */
+        @MainThread
+        fun onSuccess(request: ImageRequest, metadata: ImageResult.Metadata) {}
     }
 
     class Builder {

coil-base/src/main/java/coil/request/ImageResult.kt

@@ -20,7 +20,7 @@ sealed class ImageResult {
      *
      * @param memoryCacheKey The cache key for the image in the memory cache.
      *  It is null if the image was not written to the memory cache.
-     * @param isSampled True if [drawable] is sampled (i.e. loaded into memory at less than its original size).
+     * @param isSampled True if the image is sampled (i.e. loaded into memory at less than its original size).
      * @param dataSource The data source that the image was loaded from.
      * @param isPlaceholderMemoryCacheKeyPresent True if the request's [ImageRequest.placeholderMemoryCacheKey] was
      *  present in the memory cache and was set as the placeholder.

coil-base/src/main/java/coil/request/NullRequestData.kt

@@ -1,7 +1,7 @@
 package coil.request
 
 /**
- * Returned by [ImageRequest.data] if the request was built with null data.
+ * The value for [ImageRequest.data] if the request's data was not set or was set to null.
  *
  * @see ImageRequest.data
  */

coil-base/src/main/java/coil/size/DisplaySizeResolver.kt

@@ -2,10 +2,9 @@ package coil.size
 
 import android.content.Context
 import coil.request.ImageRequest
-import coil.target.Target
 
 /**
- * A [SizeResolver] that constrains a [Target] to the size of the display.
+ * A [SizeResolver] that measures the size of the display.
  *
  * This is used as the fallback [SizeResolver] for [ImageRequest]s.
  */

coil-base/src/test/java/coil/request/RequestServiceTest.kt

@@ -116,7 +116,7 @@ class RequestServiceTest {
     }
 
     @Test
-    fun `allowInexactSize - GetRequest`() {
+    fun `allowInexactSize - PixelSizeResolver explicit`() {
         val request = createRequest(context) {
             size(100, 100)
         }

coil-gif/README.md

@@ -5,7 +5,7 @@ Unlike Glide, GIFs are not supported by default. However, Coil has an extension
 To add GIF support, import the extension library:
 
 ```kotlin
-implementation("io.coil-kt:coil-gif:0.11.0")
+implementation("io.coil-kt:coil-gif:0.12.0")
 ```
 
 And add the decoders to your component registry when constructing your `ImageLoader`:

coil-svg/README.md

@@ -3,7 +3,7 @@
 To add SVG support, import the extension library:
 
 ```kotlin
-implementation("io.coil-kt:coil-svg:0.11.0")
+implementation("io.coil-kt:coil-svg:0.12.0")
 ```
 
 And add the decoder to your component registry when constructing your `ImageLoader`:

coil-video/README.md

@@ -3,7 +3,7 @@
 To add video frame support, import the extension library:
 
 ```kotlin
-implementation("io.coil-kt:coil-video:0.11.0")
+implementation("io.coil-kt:coil-video:0.12.0")
 ```
 
 And add the two fetchers to your component registry when constructing your `ImageLoader`:

deploy_docs.sh

@@ -15,9 +15,10 @@ cp coil-svg/README.md docs/svgs.md
 cp coil-video/README.md docs/videos.md
 cp logo.svg docs/logo.svg
 cp README-ko.md docs/README-ko.md
+cp README-zh.md docs/README-zh.md
 
 # Deploy to Github pages.
 mkdocs gh-deploy
 
 # Clean up.
-rm docs/index.md docs/contributing.md docs/changelog.md docs/logo.svg docs/gifs.md docs/svgs.md docs/videos.md docs/README-ko.md
+rm docs/index.md docs/contributing.md docs/changelog.md docs/logo.svg docs/gifs.md docs/svgs.md docs/videos.md docs/README-ko.md docs/README-zh.md