Revisit docs 1/n: Get Started + Tutorial (#6089)

* remove apollo-adapters from these docs

* move KDoc and Changelog up

* add a list of modules

* fix page name and section indentation

* Add "add Android Studio plugin"

* Nicer modules page

* fix screenshot shadow

* Revisit tutorial error handling

* wording

* wording

* wording

* wording

Author: martinbonnin

docs/source/config.json

@@ -7,6 +7,7 @@
   "sidebar": {
     "Get Started": "/",
     "Migrating to v4": "/migration/4.0",
+    "Modules": "/essentials/modules",
     "Evolution policy": "/essentials/evolution",
     "Kdoc": "https://apollographql.github.io/apollo-kotlin/kdoc/",
     "Changelog": "https://github.com/apollographql/apollo-kotlin/blob/main/CHANGELOG.md",

docs/source/essentials/modules.mdx

@@ -0,0 +1,188 @@
+---
+title: Modules
+---
+
+Apollo Kotlin is highly modular, making it easy to only include the features that you use and exclude the others, keeping your binary size and compile times small.
+
+All the modules are documented in the [KDoc API reference](https://apollographql.github.io/apollo-kotlin/kdoc/)
+
+## Main modules
+
+### apollo-annotations
+
+`apollo-annotations` is a very small module that contains `@ApolloExperimental` and other annotations mainly useful for handling API lifecycle.
+
+It is an API dependency of most of the other modules.
+
+### apollo-api
+
+`apollo-api` contains the bare minimum symbols to compile the generated code and parse responses.
+
+It does not contain any networking or caching code. For a more complete artifact, see `apollo-runtime`. 
+
+See ["Using the models without apollo-runtime"](https://www.apollographql.com/docs/kotlin/advanced/no-runtime) for how to use `apollo-api`.
+
+### apollo-ast
+
+`apollo-ast` contains code to parse GraphQL documents and manipulate their Abstract Syntax Tree.
+
+See ["Apollo AST"](https://www.apollographql.com/docs/kotlin/advanced/apollo-ast) for how to use `apollo-ast`.
+
+### apollo-compiler
+
+`apollo-compiler` is the low level compiler API used by apollo-gradle-plugin.
+
+`apollo-compiler` uses [JavaPoet](https://github.com/square/javapoet) and [KotlinPoet](https://github.com/square/kotlinpoet) to generate Java and Kotlin models from GraphQL operations.
+
+`apollo-compiler` is usually consumed through Gradle or Maven plugins. It also contains `ApolloCompilerPlugin`.
+
+See ["Apollo Compiler plugins"](https://www.apollographql.com/docs/kotlin/advanced/compiler-plugins) for how to develop compiler plugins.
+
+### apollo-debug-server
+
+`apollo-debug-server` is a server that serves your normalized cache to the IntelliJ/Android Studio plugin.
+
+### apollo-gradle-plugin
+
+`apollo-gradle-plugin` contains the Apollo Gradle plugin.
+
+This module shadows and relocates its runtime dependencies to avoid classpath issues. This can make debugging harder in some cases.
+
+See `apollo-gradle-plugin-external` for a version of `apollo-gradle-plugin` that does not shadow its dependencies.
+
+See ["Gradle Plugin Configuration"](https://www.apollographql.com/docs/kotlin/advanced/plugin-configuration/) for how to use the Gradle plugin.
+
+### apollo-gradle-plugin-external
+
+`apollo-gradle-plugin-external` contains the Apollo Gradle plugin.
+
+This module does not shadow its runtime dependencies, making it more prone to Gradle classpath issues.
+
+See `apollo-gradle-plugin` for a version of `apollo-gradle-plugin-external` that shadow its dependencies.
+
+See ["Gradle Plugin Configuration"](https://www.apollographql.com/docs/kotlin/advanced/plugin-configuration/) for how to use the Gradle plugin.
+
+### apollo-http-cache
+
+apollo-http-cache is a HTTP cache for your GraphQL operations. Compared to a regular HTTP cache, it also caches POST requests.
+
+See ["HTTP cache"](https://www.apollographql.com/docs/kotlin/caching/http-cache) for how to use the HTTP cache
+
+### apollo-normalized-cache
+
+`apollo-normalized-cache contains` `ApolloStore` and `ApolloCacheInterceptor`. It bridges `ApolloClient` and `ApolloNormalizedCache`.
+
+See ["Normalized Caches"](https://www.apollographql.com/docs/kotlin/caching/normalized-cache#in-memory-cache) for how to use the normalized cache.
+
+### apollo-normalized-cache-api
+
+`apollo-normalized-cache-api` is the low-level cache. It knows nothing about coroutines and/or `apollo-runtime` and contains a memory implementation of `NormalizedCache`.
+
+Most of the time, use `apollo-normalized-cache` instead.
+
+See ["Normalized Caches"](https://www.apollographql.com/docs/kotlin/caching/normalized-cache#in-memory-cache) for how to use the normalized cache.
+
+### apollo-normalized-cache-sqlite
+
+`apollo-normalized-cache-sqlite` contains an implementation of `NormalizedCache` that uses SQLite to persist the data across app restarts.
+
+See ["Normalized Caches"](https://www.apollographql.com/docs/kotlin/caching/normalized-cache#in-memory-cache) for how to use the normalized cache.
+
+### apollo-runtime
+
+`apollo-runtime` contains `ApolloClient`, networking code to execute your queries and subscriptions. This is the main entry point.
+
+See ["Get Started"](https://www.apollographql.com/docs/kotlin/) for how to instantiate and use an `ApolloClient`.
+
+### apollo-testing-support
+
+`apollo-testing-support` contains:
+
+* `QueueTestNetworkTransport` and `MapTestNetworkTransport` for testing without a mock server.
+* a set of helper functions used for Apollo tests. They were never really intended to become public and will be removed in a future version. These symbols are marked as deprecated. If you are using them, copy paste them in your project.
+
+See ["Mocking GraphQL responses"](https://www.apollographql.com/docs/kotlin/testing/mocking-graphql-responses) for how to use test network transports.
+
+## Deprecated modules
+
+These modules are deprecated and will be removed in a future version. 
+
+### apollo-adapters (DEPRECATED)
+
+`apollo-adapters` contains adapters for common date and big decimal GraphQL scalars.
+
+This module is deprecated and moved to the Apollo Galaxy. See the [Apollo Galaxy page](https://www.apollographql.com/docs/kotlin/advanced/galaxy) for more details.  
+
+### apollo-api-java (DEPRECATED)
+
+`apollo-api-java` contains the symbols needed to compile the Java models.
+
+This module is deprecated and moved to the Apollo Galaxy. See the [Apollo Galaxy page](https://www.apollographql.com/docs/kotlin/advanced/galaxy) for more details.
+
+### apollo-engine-ktor (DEPRECATED)
+
+`apollo-engine-ktor` is an implementation of `HttpEngine` and `WebSocketEngine` that uses Ktor.
+
+This module is deprecated and moved to the Apollo Galaxy. See the [Apollo Galaxy page](https://www.apollographql.com/docs/kotlin/advanced/galaxy) for more details.
+
+### apollo-idling-resource (DEPRECATED)
+
+`apollo-idling-resource` contains an [Espresso `IdlingResource`](https://developer.android.com/training/testing/espresso/idling-resource) that monitors calls to your GraphQL API.
+
+This module is deprecated as we recommend you should wait for your UI to change instead. See [this article about ways to do so](https://medium.com/androiddevelopers/alternatives-to-idling-resources-in-compose-tests-8ae71f9fc473).
+
+### apollo-mockserver (DEPRECATED)
+
+`apollo-mockserver` is a HTTP server for your tests. It supports multiplatform and websockets.
+
+The API is minimal and performance is a non-goal. Do not use for production APIs.
+
+This module is deprecated and moved to the Apollo Galaxy. See the [Apollo Galaxy page](https://www.apollographql.com/docs/kotlin/advanced/galaxy) for more details.
+
+### apollo-runtime-java (DEPRECATED)
+
+`apollo-runtime-java` is an implementation of `ApolloClient` that doesn't use coroutines and more generally is more friendly for Java callers.
+
+This module is deprecated and moved to the Apollo Galaxy. See the [Apollo Galaxy page](https://www.apollographql.com/docs/kotlin/advanced/galaxy) for more details.
+
+### apollo-rx2-support (DEPRECATED)
+
+`apollo-rx2-support` provides thin wrappers around [`kotlinx-coroutines-rx2`](https://github.com/Kotlin/kotlinx.coroutines/tree/master/reactive/kotlinx-coroutines-rx2).
+
+This module is deprecated and will be removed in a future version.
+
+### apollo-rx3-support (DEPRECATED)
+
+`apollo-rx3-support` provides thin wrappers around [`kotlinx-coroutines-rx3`](https://github.com/Kotlin/kotlinx.coroutines/tree/master/reactive/kotlinx-coroutines-rx3).
+
+This module is deprecated and will be removed in a future version.
+
+### apollo-rx2-support-java (DEPRECATED)
+
+`apollo-rx2-support-java` provides adapter from `ApolloCall` to their RxJava3 equivalent.
+
+This module is deprecated and moved to the Apollo Galaxy. See the [Apollo Galaxy page](https://www.apollographql.com/docs/kotlin/advanced/galaxy) for more details.
+
+### apollo-rx3-support-java (DEPRECATED)
+
+`apollo-rx3-support-java` provides adapter from `ApolloCall` to their RxJava3 equivalent.
+
+This module is deprecated and moved to the Apollo Galaxy. See the [Apollo Galaxy page](https://www.apollographql.com/docs/kotlin/advanced/galaxy) for more details.
+
+## Internal modules
+
+These modules are published for technical reasons only. Most of their symbols are `@ApolloInternal` and they might be removed at any time. Avoid using them.
+
+### apollo-mockserver (INTERNAL)
+
+`apollo-mpp-utils` contains a few utilities for working with multiplatform projects.
+
+As of June 2024, it only contains `currentTimeMillis`. In most cases, we should replace that with `kotlin.time.TimeMark` but it's still used in `HttpInfo` as absolute timestamps, and we can't remove it just yet.
+
+This module is published for technical reasons only. Do not use directly.
+
+### apollo-tooling (INTERNAL)
+
+`apollo-tooling` contains APIs to work with GraphQL schemas and operations as well as the GraphOS API. It is used from the CLI and Gradle plugin
+
+This module is published for technical reasons only. Do not use directly.

docs/source/index.md

@@ -113,11 +113,10 @@ Here's the current matrix of supported features per platform:
 |                                                      | `jvm` | `Apple¹` | `js` | `wasmJs` | `linuxX64` |
 |------------------------------------------------------|:-----:|:--------:|:----:|:--------:|:----------:|
 | `apollo-api` (models)                                |   ✅   |    ✅     |  ✅   |    ✅     |     ✅      |
-| `apollo-runtime` (network, query batching, apq, ...) |   ✅   |    ✅     |  ✅   |    ✅     |     🚫      |
-| `apollo-normalized-cache`                            |   ✅   |    ✅     |  ✅   |    ✅     |     🚫      |
-| `apollo-adapters`                                    |   ✅   |    ✅     |  ✅   |    ✅     |     🚫      |
-| `apollo-normalized-cache-sqlite`                     |   ✅   |    ✅     |  🚫   |    🚫     |     🚫      |
-| `apollo-http-cache`                                  |   ✅   |    🚫     |  🚫   |    🚫     |     🚫      |
+| `apollo-runtime` (network, query batching, apq, ...) |   ✅   |    ✅     |  ✅   |    ✅     |     🚫     |
+| `apollo-normalized-cache`                            |   ✅   |    ✅     |  ✅   |    ✅     |     🚫     |
+| `apollo-normalized-cache-sqlite`                     |   ✅   |    ✅     |  🚫  |    🚫    |     🚫     |
+| `apollo-http-cache`                                  |   ✅   |    🚫    |  🚫  |    🚫    |     🚫     |
 
 ¹: Apple currently includes:
 

docs/source/tutorial/01-configure-project.mdx

@@ -31,6 +31,14 @@ You should see a list with static placeholder data:
 
 Now let's add Apollo Kotlin to the project.
 
+## Install the Android Studio Plugin (optional)
+
+We recommend installing the [Android Studio Plugin](https://www.apollographql.com/docs/kotlin/testing/android-studio-plugin/) to benefit from autocomplete in your `.graphql`, live code generation and more.
+
+Go to `Android Studio` -> `Setting...` -> `Plugins`. In the "Marketplace" tab, search for "Apollo" and install the Apollo Android Studio Plugin
+
+<img src="images/add-ij-plugin.png" alt="A dialog showing how to install the Android Studio plugin" class="screenshot"/>
+
 ## Get the latest version of Apollo Kotlin
 
 You can find the latest version of Apollo Kotlin from the [GitHub releases page](https://github.com/apollographql/apollo-kotlin/releases). It is also displayed at the top of the [apollo-kotlin repo](https://github.com/apollographql/apollo-kotlin/).

docs/source/tutorial/08-add-a-details-view.mdx

@@ -118,19 +118,22 @@ fun LaunchDetails(launchId: String) {
 }
 ```
 
-## Handle protocol errors
+## Handle errors
 
-As you execute your query, two types of errors can happen:
+As you execute your query, different types of errors can happen:
 
-* Protocol errors: connectivity issues, HTTP errors, or JSON parsing errors. In this case, `response.exception` will contain an `ApolloException`, and `response.data` will be null.
-* Application errors. In this case, `response.errors` will contain the application errors and `response.data` might be `null`.
+* Fetch errors: connectivity issues, HTTP errors, JSON parsing errors, etc... In this case, `response.exception` contains an `ApolloException`. Both `response.data` and `response.errors` is null.
+* GraphQL [request errors](https://spec.graphql.org/draft/#request-error): in this case, `response.errors` contains the GraphQL errors. `response.data` is null.
+* GraphQL [field errors](https://spec.graphql.org/draft/#field-error): in this case, `response.errors` contains the GraphQL errors. `response.data` contains partial data.
+
+Let's handle the first two for now: fetch errors and GraphQL request errors. 
 
 First let's create a `LaunchDetailsState` sealed interface that will hold the possible states of the UI:
 
 ```kotlin title="app/src/main/java/com/example/rocketreserver/LaunchDetails.kt"
 private sealed interface LaunchDetailsState {
     object Loading : LaunchDetailsState
-    data class ProtocolError(val exception: ApolloException) : LaunchDetailsState
+    data class Error(val message: String) : LaunchDetailsState
     data class Success(val data: LaunchDetailsQuery.Data) : LaunchDetailsState
 }
 ```
@@ -144,11 +147,12 @@ fun LaunchDetails(launchId: String) {
     LaunchedEffect(Unit) {
         val response = apolloClient.query(LaunchDetailsQuery(launchId)).execute()
         state = when {
-            response.exception != null -> {
-              ProtocolError(response.exception!!)
+            response.data != null -> {
+              // Handle (potentially partial) data
+              LaunchDetailsState.Success(response.data!!)
             }
             else -> {
-              Success(response.data!!)
+              LaunchDetailsState.Error("Oh no... An error happened.")
             }
         }
     }
@@ -158,63 +162,57 @@ fun LaunchDetails(launchId: String) {
 Now use the state to show the appropriate UI:
 
 ```kotlin title="app/src/main/java/com/example/rocketreserver/LaunchDetails.kt"
+    
     // Use the state
     when (val s = state) {
         Loading -> Loading()
-        is ProtocolError -> ErrorMessage("Oh no... A protocol error happened: ${s.exception.message}")
+        is Error -> ErrorMessage(s.message)
         is Success -> LaunchDetails(s.data)
     }
 }
 ```
 
 Enable airplane mode before clicking the details of a launch. You should see this:
 
-<img src="images/error_protocol.png" alt="Oh no" class="screenshot" width="300"/>
+<img src="images/error_generic.png" alt="Oh no" class="screenshot" width="300"/>
 
-This is good! But it's not enough. Even if the request executes correctly at the protocol level, it might also contain application errors that are specific to your server.
+This is good! 
 
-## Handle application errors
+This method handles fetch and GraphQL request errors but ignores GraphQL field errors. 
 
-To handle application errors, you can check `response.hasErrors()`. First, add a new state to the sealed interface:
+If a GraphQL field error happens, the corresponding Kotlin property is `null` and an error is present in `response.errors`: your response contains partial data!
 
-```kotlin title="app/src/main/java/com/example/rocketreserver/LaunchDetails.kt"
-private sealed interface LaunchDetailsState {
-    object Loading : LaunchDetailsState
-    data class ProtocolError(val exception: ApolloException) : LaunchDetailsState
-    data class ApplicationError(val errors: List<Error>) : LaunchDetailsState // highlight-line
-    data class Success(val data: LaunchDetailsQuery.Data) : LaunchDetailsState
-}
-```
+Handling this partial data in your UI code can be complicated. You can handle them earlier by looking at `response.errors`. 
+
+## Handle partial data
 
-Then, in the `when` block, check for `response.hasErrors()` and wrap the result in the new state:
+To handle GraphQL field errors globally and make sure the returned data is not partial, use `response.errors`:
 
 ```kotlin title="app/src/main/java/com/example/rocketreserver/LaunchDetails.kt"
 state = when {
-    response.exception != null -> {
-        ProtocolError(response.exception!!)
-    }
-    response.hasErrors() -> { // highlight-line
-        ApplicationError(response.errors!!) // highlight-line
-    } // highlight-line
-    else -> {
-        Success(response.data!!)
-    }
+  response.errors.orEmpty().isNotEmpty() -> {
+    // GraphQL error
+    LaunchDetailsState.Error(response.errors!!.first().message) // highlight-line
+  }
+  response.exception is ApolloNetworkException -> {
+    // Network error
+    LaunchDetailsState.Error("Please check your network connectivity.")
+  }
+  response.data != null -> {
+    // data (never partial)
+    LaunchDetailsState.Success(response.data!!)
+  }
+  else -> {
+    // Another fetch error, maybe a cache miss?
+    // Or potentially a non-compliant server returning data: null without an error
+    LaunchDetailsState.Error("Oh no... An error happened.")
+  }
 }
 ```
 
-You should also update the conditional expression to handle the `ApplicationError` case:
-```kotlin title="app/src/main/java/com/example/rocketreserver/LaunchDetails.kt"
-    when (val s = state) {
-        Loading -> Loading()
-        is ApplicationError -> ErrorMessage(text = s.errors.first().message) // highlight-line
-        is ProtocolError -> ErrorMessage("Oh no... A protocol error happened: ${s.exception.message}")
-        is Success -> LaunchDetails(s.data)
-    }
-```
-
 `response.errors` contains details about any errors that occurred. Note that this code also null-checks `response.data!!`. In theory, a server should not set `response.data == null` and `response.hasErrors == false` at the same time, but the type system cannot guarantee this.
 
-To trigger an error, replace `LaunchDetailsQuery(launchId)` with `LaunchDetailsQuery("invalidId")`. Disable airplane mode and select a launch. The server will send this response:
+To trigger a GraphQL field error, replace `LaunchDetailsQuery(launchId)` with `LaunchDetailsQuery("invalidId")`. Disable airplane mode and select a launch. The server will send this response:
 
 ```json title="(error)"
 {