Documentation tweaks and updates for v4 (#5954)

* Documentation tweaks

* Update docs/source/caching/normalized-cache.mdx

Co-authored-by: Martin Bonnin <[email protected]>

* Address a few review comments

* Address a few review comments

* Revert "cache ID" -> "cache key"

---------

Co-authored-by: Martin Bonnin <[email protected]>

Author: BoD

.idea/codeStyles/Project.xml

@@ -19,3 +19,4 @@
 /advanced/test-builders/ /docs/kotlin/testing/test-builders/
 /advanced/response-based-codegen/ /docs/kotlin/advanced/response-based/
 /advanced/codegen-methods/ /docs/kotlin/advanced/response-based/
+/advanced/source-sets/ /docs/kotlin/advanced/plugin-configuration/#wiring-generated-sources

docs/source/_redirects

@@ -4,7 +4,7 @@ title: Apollo AST
 
 To generate client code, Apollo Kotlin parses both your GraphQL schema _and_ each operation you write against it into an **Abstract Syntax Tree** ([AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree)). An AST represents a GraphQL document in a type-safe, machine-readable format.
 
-Apollo Kotlin's parser has its own module (`apollo-ast`), which you can use independently of `apollo-runtime` or `apollo-api`.
+The Apollo Kotlin parser has its own artifact (`apollo-ast`), which you can use independently of `apollo-runtime` or `apollo-api`.
 
 Features of `apollo-ast` include:
 
@@ -29,7 +29,7 @@ dependencies {
 
 Use the `parseAsGQLDocument` method to parse a document from a `File`, a `String`, or an Okio [`BufferedSource`](https://square.github.io/okio/3.x/okio/okio/okio/-buffered-source/index.html).
 
-```kotlin {12}
+```kotlin {13}
 val graphQLText = """
     query HeroForEpisode(${"$"}ep: Episode) {
       hero(episode: ${"$"}ep) {

docs/source/advanced/apollo-ast.mdx

@@ -2,13 +2,13 @@
 title: Authenticate your operations
 ---
 
-> Authentication is not included in the GraphQL specification. This page aims at giving some guidance for the most common scenarios but doesn't pretend to be exhaustive.
+> Authentication is not included in the GraphQL specification. This page aims at giving some guidance for the most common scenarios but doesn't intend to be exhaustive.
 
 ## Authenticating your HTTP requests with OkHttp
 
 [OkHttp Interceptors](https://square.github.io/okhttp/features/interceptors/) are an easy way to add an `"Authorization"` header to your HTTP requests.
 
-OkHttp Interceptors have been around for a long time and work well but only work on Android and the JVM.
+OkHttp Interceptors have been around for a long time and work well but can only be used with Apollo Kotlin on Android and the JVM.
 
 ## Authenticating your HTTP requests with Apollo HttpInterceptor
 
@@ -69,10 +69,10 @@ Alternatively, you can also send headers in the initial WebSocket handshake requ
 
 ```kotlin
 val apolloClient = ApolloClient.Builder()
-    .httpServerUrl("http://localhost:8080/graphql")
+    .httpServerUrl("https://example.com/graphql")
     .subscriptionNetworkTransport(
         WebSocketNetworkTransport.Builder()
-            .serverUrl("http://localhost:8080/subscriptions")
+            .serverUrl("https://example.com/subscriptions")
             .addHeader("Authorization", authorization) // highlight-line
             .build()
     )
@@ -83,7 +83,11 @@ val apolloClient = ApolloClient.Builder()
 
 When using authenticated subscriptions over WebSockets, you might want to refresh your authentication token because it was invalidated or simply because it expired.
 
-> Note: if your user logged out, you might want to consider creating a new `ApolloClient` instead. This will make sure that all other state besides the WebSocket, like cache for an example, is new and not shared amongst different users.
+<Note>
+
+If your user logged out, you might want to consider creating a new `ApolloClient` instead. This will make sure that all other state besides the WebSocket, like cache for an example, is new and not shared amongst different users.
+
+</Note>
 
 Sometimes the websocket will emit an error that you can use in `webSocketReopenWhen` to create a new WebSocket. Other times that information will come from elsewhere in your app and you will have to force disconnect the WebSocket.
 

docs/source/advanced/authentication.mdx

@@ -6,7 +6,7 @@ GraphOS Studio users can opt-in [Client Awareness](https://www.apollographql.com
 
 Client Awareness uses `apollographql-client-name` and `apollographql-client-version` custom HTTP headers to report client usage.
 
-Enable it by adding an `ApolloClientAwarenessInterceptor` to your `OkHttpClient`:
+Enable it by adding an `ApolloClientAwarenessInterceptor` to your `ApolloClient`:
 
 ```kotlin
 val apolloClient = ApolloClient.Builder()
@@ -15,4 +15,6 @@ val apolloClient = ApolloClient.Builder()
     .build()
 ```
 
-**Note**: This example uses `BuildConfig` to set the applicationId as client name and app version as client version but you can override this. Especially, if your iOS and Android apps use the same package name, it's useful to customize it to allow differentiating the clients
+<Note>
+This example uses `BuildConfig` to set the app's `applicationId` as the client name and its `versionName` as the client version, but you can override this. Especially, if your iOS and Android apps use the same package name, it's useful to customize it to be able to differentiate the clients.
+</Note>

docs/source/advanced/client-awareness.mdx

@@ -2,6 +2,12 @@
 title: Apollo compiler plugins
 ---
 
+<ExperimentalFeature>
+
+**Compiler plugins are currently [experimental](https://www.apollographql.com/docs/resources/release-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on them, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md) or in the [Kotlin Slack community](https://slack.kotl.in/).
+
+</ExperimentalFeature>
+
 The Apollo compiler supports [a wide range of options](../advanced/plugin-configuration). For the cases where these options are not enough, you can use Apollo compiler plugins to modify the behaviour of the compiler. 
 
 Apollo compiler plugins allow to:
@@ -140,6 +146,6 @@ Because codegen is run in a separate classloader when using compiler plugins, it
 
 ## Other references
 
-For other plugin APIs like layout, IR, JavaPoet and KotlinPoet transforms, check out the [ApolloCompilerPlugin API docs](https://www.apollographql.com/docs/kotlin/kdoc/apollo-compiler/com.apollographql.apollo3.compiler/-apollocompilerplugin/index.html)
+For other plugin APIs like layout, IR, JavaPoet and KotlinPoet transforms, check out the [ApolloCompilerPlugin API docs](https://www.apollographql.com/docs/kotlin/kdoc/apollo-compiler/com.apollographql.apollo3.compiler/-apollo-compiler-plugin/index.html)
 
 For more examples, check out the [integration-tests](https://github.com/apollographql/apollo-kotlin/tree/main/tests/compiler-plugins).

docs/source/advanced/compiler-plugins.mdx

@@ -1,9 +1,12 @@
 ---
-title: Experimental websockets
+title: Experimental WebSockets
 ---
 
-> ⚠️ **Experimental websockets APIs are [experimental](https://www.apollographql.com/docs/resources/release-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on them, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md&title=[Defer%20Support]) or in the [Kotlin Slack community](https://slack.kotl.in/).
+<ExperimentalFeature>
 
+**The experimental WebSockets implementation are currently [experimental](https://www.apollographql.com/docs/resources/release-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on them, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md) or in the [Kotlin Slack community](https://slack.kotl.in/).
+
+</ExperimentalFeature>
 
 Historically, WebSockets have been one of the most complex and error-prone parts of Apollo Kotlin because:
 
@@ -25,7 +28,7 @@ The `com.apollographql.apollo3.network.websocket` implementation provides the fo
 
 While they are `@ApolloExperimental`, we believe the new `.websocket` APIS to be more robust than the non-experimental `.ws` ones. They are safe to use in non-lib use cases.
 
-The "experimental" tag is to account for required API breaking changes based on community feedback. Ideally no change is needed.
+The "experimental" tag is to account for required API breaking changes based on community feedback. Ideally no change will be needed.
 
 After a feedback phase, the current `.ws` APIs will become deprecated and the `.websocket` one promoted to stable by removing the `@ApolloExperimental` annotations. 
 
@@ -117,10 +120,10 @@ val apolloClient = ApolloClient.Builder()
             .serverUrl(url)
             .build()
     )
-    .addRetryOnErrorInterceptor { apolloRequest, exception, attempt -> 
+    .addRetryOnErrorInterceptor { exception, attempt -> 
       // retry logic here
 
       // return true to retry or false to terminate the Flow
       true
     }
-```
+```

docs/source/advanced/experimental-websockets.mdx

@@ -4,15 +4,39 @@ title: Using a custom HTTP client
 
 By default, Apollo Kotlin uses the following HTTP clients for different platforms/languages:
 
-| Platform | HTTP Client |
-|----------|-------------|
-| Android  | [OkHttp](https://square.github.io/okhttp/) |
-| JavaScript | [Ktor](https://ktor.io/) |
-| iOS/MacOS | [NSURLSesssion](https://developer.apple.com/documentation/foundation/nsurlsession) |
+| Platform        | HTTP Client                                                                                                                                                                  |
+|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Android/JVM     | [OkHttp](https://square.github.io/okhttp/)                                                                                                                                   |
+| JavaScript/Wasm | [fetch()](https://developer.mozilla.org/en-US/docs/Web/API/fetch) / [Node Fetch](https://www.npmjs.com/package/node-fetch) for HTTP, [Ktor](https://ktor.io/) for WebSockets |
+| iOS/MacOS       | [NSURLSesssion](https://developer.apple.com/documentation/foundation/nsurlsession)                                                                                           |
 
-You can use a different HTTP client with Apollo Kotlin by creating a custom class that implements the `HttpEngine` interface.
 
-## The `HttpEngine` interface
+## Ktor engine
+
+Additionally, an optional implementation based on [Ktor](https://ktor.io/) for all targets is available in the `apollo-engine-ktor` module. To use it, add the following dependency to your project:
+
+```kotlin title="build.gradle[.kts]"
+dependencies {
+  // ...
+  implementation("com.apollographql.apollo3:apollo-engine-ktor:4.0.0-beta.7")
+}
+```
+
+And configure your `ApolloClient` to use the Ktor engine:
+
+```kotlin
+val client = ApolloClient.Builder()
+  .serverUrl("https://example.com/graphql")
+  // Create a new Ktor engine
+  .httpEngine(KtorHttpEngine())
+  // Or, if you want to reuse an existing Ktor client
+  .ktorClient(myKtorClient)
+  .build()
+```
+
+## Implement your own HTTP engine
+
+You can use a different HTTP client with Apollo Kotlin by creating a custom class that implements the `HttpEngine` interface.
 
 The [HttpEngine interface](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-runtime/com.apollographql.apollo3.network.http/-http-engine/index.html)
 defines two functions: `execute` and `close`. Here's an example implementation that also includes a couple of helper
@@ -63,14 +87,14 @@ class MyHttpEngine(val wrappedClient: MyClient) : HttpEngine {
 
 This example uses an asynchronous `wrappedClient` that runs the network request in a separate thread. Note that because `HttpEngine.execute` itself is called from a background thread, you can safely block in `execute()`.
 
-## Using your `HttpEngine`
+### Using your `HttpEngine`
 
 After you create your `HttpEngine` implementation, you can register it with your [`ApolloClient`](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-runtime/com.apollographql.apollo3/-apollo-client/index.html) instance using [`ApolloClient.Builder.httpEngine`](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-runtime/com.apollographql.apollo3/-apollo-client/-builder/http-engine.html):
 
 ```kotlin
 // Use your HttpEngine
 val client = ApolloClient.Builder()
-  .serverUrl(serverUrl = "https://com.example/graphql")
+  .serverUrl(serverUrl = "https://example.com/graphql")
   .httpEngine(httpEngine = MyHttpEngine(wrappedClient))
   .build()
 ```

docs/source/advanced/http-engine.mdx

@@ -1,12 +1,12 @@
 ---
-title: Using with Java
+title: Using Java
 ---
 
 This article describes how to use Apollo Kotlin in Java projects.
 
 ## Use the Java codegen
 
-Apollo Kotlin generates Kotlin code by default, but you can configure it to use the Java codegen instead:
+Apollo Kotlin generates Kotlin code by default, but you can configure it to generate Java code instead:
 
 ```kotlin title="build.gradle[.kts]"
 apollo {
@@ -39,7 +39,7 @@ import com.apollographql.apollo3.runtime.java.ApolloClient;
 
 // Create and configure an ApolloClient
 ApolloClient client = ApolloClient.Builder builder = new ApolloClient.Builder()
-  .serverUrl("http://localhost:4000/graphql")
+  .serverUrl("https://example.com/graphql")
   .build();
 
 // Call enqueue() to execute a query asynchronously
@@ -79,7 +79,7 @@ When executing subscriptions with the Java runtime, the callback passed to `enqu
 
 ```java
 ApolloClient apolloClient = new ApolloClient.Builder()
-  .serverUrl("http://localhost:4000/graphql")
+  .serverUrl("https://example.com/graphql")
   // Configure a protocol factory
   .wsProtocolFactory(new ApolloWsProtocol.Factory())
   .build();

docs/source/advanced/java.mdx

@@ -20,7 +20,11 @@ To work around this, Apollo Kotlin provides two alternative solutions to work wi
 the [@JsExport](https://kotlinlang.org/docs/js-to-kotlin-interop.html#jsexport-annotation) annotation so that the
 dynamic JS object is callable from Kotlin directly.
 
-> ℹ️ `JsExport` is an experimental feature in Kotlin and Apollo Kotlin and may change in future versions.
+<ExperimentalFeature>
+
+**`JsExport` is currently [experimental](https://www.apollographql.com/docs/resources/release-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on it, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md) or in the [Kotlin Slack community](https://slack.kotl.in/).
+
+</ExperimentalFeature>
 
 Because it bypasses the Kotlin type system, using `jsExport` comes with limitations.
 See [Limitations](#Limitations) for more details.
@@ -50,8 +54,7 @@ expect suspend fun <D : Operation.Data> JsonHttpClient.executeApolloOperation(
 ): D?
 ```
 
-For non-JS implementations, implement `executeApolloOperation` using your favorite HTTP client (
-see [no-runtime](no-runtime)) and `parseJsonResponse`:
+For non-JS implementations, implement `executeApolloOperation` using your favorite HTTP client (see [Using the models without apollo-runtime](no-runtime)) and `parseJsonResponse`:
 
 ```kotlin
 // non-js implementation
@@ -68,8 +71,7 @@ actual suspend fun <D : Operation.Data> JsonHttpClient.executeApolloOperation(
 }
 ```
 
-On JS, you can use `fetch` and `unsafeCast()` to cast the returned javascript object into the @JsExport responseBased
-model:
+On JS, you can use `fetch` and `unsafeCast()` to cast the returned javascript object into the `@JsExport` responseBased model:
 
 ```kotlin
 // js implementation
@@ -91,8 +93,7 @@ actual suspend fun <D : Operation.Data> JsonHttpClient.executeApolloOperation(
 }
 ```
 
-For a more complete example see [this gist](https://gist.github.com/baconz/778e8a0b359267292d6e05ad81c19b90) which uses
-ktor for non-JS clients.
+For a more complete example see [this gist](https://gist.github.com/baconz/778e8a0b359267292d6e05ad81c19b90) which uses Ktor for non-JS clients.
 
 ### How it works
 
@@ -147,9 +148,8 @@ class Point {
 ```
 
 To work around this, you need to tell the compiler not to mangle property names, which you can do by annotating the
-class
-with `JsExport`. When you set the `jsExport` option on your service, you tell Apollo to annotate each generated
-class with `JsExport` so that the property names are not mangled, and you can safely cast.
+class with `@JsExport`. When you set the `jsExport` option on your service, you tell Apollo to annotate each generated
+class with `@JsExport` so that the property names are not mangled, and you can safely cast.
 
 ### Accessors and Polymorphism
 
@@ -188,14 +188,14 @@ when (animal.__typename) {
 
 ### Limitations
 
-* `JsExport` is an experimental feature in Kotlin and Apollo Kotlin and may change in future versions.
-* `JsExport` only makes sense on response based codegen since it requires the Kotlin models to have the same shape as
+* `@JsExport` is an experimental feature in Kotlin and Apollo Kotlin and may change in future versions.
+* `@JsExport` only makes sense on response based codegen since it requires the Kotlin models to have the same shape as
   the JSON.
 * On JS, is is not possible to check if a `@JsExport` instance implements a given class. If you need polymorphism, you
   must check `__typename` to determine what interface to use.
 * Extension functions on generated code break when you use this technique since we are casting a raw JS object and not
   actually instantiating a class.
-* `generateAsInternal = true` does not work with `JsExport`, since the compiler ends up giving the internal modifier
+* `generateAsInternal = true` does not work with `@JsExport`, since the compiler ends up giving the internal modifier
   precedence, and thus mangling the property names.
 * Custom adapters can only be used when their target types are supported by JS (see the full list
   of [supported types](https://kotlinlang.org/docs/js-to-kotlin-interop.html#kotlin-types-in-javascript)).
@@ -205,14 +205,14 @@ when (animal.__typename) {
 ## `DynamicJsJsonReader`
 
 If you would prefer to use `operationBased` models, and performance is not _as_ critical, you can
-use `DynamicJsJsonReader`. `DynamicJsJsonReader` works with a javascript object that is already parsed on the JS side.
+use `DynamicJsJsonReader`. `DynamicJsJsonReader` works with a JavaScript object that is already parsed on the JS side.
 
-In JS reading response byte by byte from a byte array like okio is doing incurs a lot of overhead because Kotlin
+In JS reading response byte by byte from a byte array like Okio does incurs a lot of overhead because Kotlin
 uses `Long` indices in its Arrays, and Longs do not have a JS implementation. 
 
 By bypassing this reading, `DynamicJsJsonReader` allows faster reading of responses while still keeping the full Kotlin type information. 
 
-In testing we've seen a ~25x performance boost on JS platforms using this parser vs ~100x with the `JsExport` approach.
+In testing we've seen a ~25x performance boost on JS platforms using this parser vs ~100x with the `@JsExport` approach.
 
 To use `DynamicJsJsonReader`, your JS implementation above would become: