Revisit docs 2/n: configuration + fetching (#6090)

* revisit Gradle docs

* rework multi modules

* revert unwanted changes

* fix link

* wording

* mention generateInputBuilders

* move the experimental websockets up

* Fix broken polymorphic types link

* typo

* add not about new WebSocket API

* fix syntax error

* fix syntax

* Update docs/source/advanced/plugin-recipes.mdx

Co-authored-by: Benoit 'BoD' Lubek <[email protected]>

---------

Co-authored-by: Benoit 'BoD' Lubek <[email protected]>

Author: martinbonnin

docs/source/advanced/multi-modules.mdx

@@ -60,7 +60,30 @@ apollo {
 
 By default, Apollo Kotlin generates all the types in your schema module. This is because there is no way to know in advance what types are going to be used by feature modules. 
 
-For large schemas, this can generate a lot of code and increase your build time significantly. In this case, you can opt in auto-detection of used types. This works by splitting the codegen task in different steps so that feature modules can let the schema module know what types are used before actually generating the models. To opt in, call `dependsOn()` with the `bidirectional` argument set to true:
+For large schemas, this can generate a lot of code and increase your build time significantly. In this case, you can opt in auto-detection of used types. 
+
+This works by splitting the codegen task in different steps so that feature modules can let the schema module know what types are used before actually generating the models. To opt in, call `isADependencyOf()` to establish the bidirectional dependency between your feature module and your schema module:
+
+
+```kotlin
+// schema/build.gradle.kts
+apollo {
+  service("service") {
+    packageName.set("schema")
+    generateApolloMetadata.set(true)
+    
+    isADependencyOf(project(":feature")) // highlight-line
+    // list all your feature modules here
+    isADependencyOf(project(":feature2"))
+    // ...
+  }
+}
+```
+Once you opt in auto-detection of used types, it's important that **all** modules are doubly linked like above. If not the feature modules will fail to compile due to some missing schema classes.
+
+## bidirectional parameter (Experimental)
+
+Using `isADependencyOf()` requires listing all your feature modules in your schema module which duplicates code. To keep things minimal and configure the dependency automatically, use `bidirectional = true`:
 
 ```kotlin
 // feature/build.gradle.kts
@@ -76,8 +99,7 @@ apollo {
 
 <ExperimentalFeature>
 
-The `bidirectional` parameter is experimental because it may break <a href="https://docs.gradle.org/current/userguide/build_environment.html">Gradle project isolation</a>. For a project-isolation compatible method, try <a href="https://www.apollographql.com/docs/kotlin/kdoc/apollo-gradle-plugin-external/com.apollographql.apollo.gradle.api/-service/is-a-dependency-of.html">isADependencyOf</a> 
+The `bidirectional` parameter is experimental and not compatible with <a href="https://docs.gradle.org/current/userguide/build_environment.html">Gradle project isolation</a>. 
 
 </ExperimentalFeature>
 
-Once you opt in auto-detection of used types, it's important that **all** modules are doubly linked like above. If not the feature modules will fail to compile due to some missing schema classes.

docs/source/advanced/operation-variables.mdx

@@ -4,9 +4,7 @@ title: Using GraphQL variables in Apollo Kotlin
 
 GraphQL supports passing argument values to your operations with [variables](https://graphql.org/graphql-js/passing-arguments/). This enables you to write a single query that you can reuse with multiple variable values (this is a [recommended best practice](/react/data/operation-best-practices/#use-variables-to-provide-graphql-arguments)).
 
-In GraphQL, non-nullable variables are required, and nullable variables are optional. However, because variables are rarely omitted in practice, Apollo Kotlin provides a mechanism to make variables non-optional in generated code. This makes the structure of generated code more straightforward.
-
-Because you might still need to omit variables, the default is to generate them as optional, but you can configure this (for specific variables or globally).
+In GraphQL, non-nullable variables are required, and nullable variables are always optional. Apollo Kotlin uses its own [`Optional`](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-api/com.apollographql.apollo.api/-optional/index.html) type to distinguish between present (but maybe nullable) and absent types.
 
 Consider the following GraphQL query with two nullable variables:
 
@@ -39,45 +37,36 @@ val query = GetTodosQuery(Optional.Present(null), Optional.Present(null))
 val query = GetTodosQuery(Optional.Present(100), Optional.Present(0))
 ```
 
-## Making nullable variables non-optional
+## Using input builders
+
+For both operations and input objects, having to wrap values in an [`Optional`](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-api/com.apollographql.apollo.api/-optional/index.html) wrapper can be cumbersome.
 
-To disable optional variables globally, update your Gradle config like so:
+For those cases, use `generateInputBuilders`:
 
 ```kotlin
 apollo {
   service("service") {
     // ...
-    generateOptionalOperationVariables.set(false)
+    generateInputBuilders.set(true)
   }
 }
 ```
 
-If you do, in the case of the `GetTodos` query shown above, Apollo Kotlin now generates the following code:
-
-```kotlin
-class GetTodosQuery(val first: Int?, val offset: Int?)
-```
-
-This makes the calling code less verbose to use:
+If you do, in the case of the `GetTodos` query shown above, Apollo Kotlin now generates a `Builder` for each operation:
 
 ```kotlin
+// Omit values for both variables
+val query = GetTodosQuery.Builder()
+               .build()
 // Provide null for both variables
-val query = GetTodosQuery(null, null)
+val query = GetTodosQuery.Builder()
+               .first(null)
+               .offset(null)
+               .build()
 // Send explicit values for both variables
-val query = GetTodosQuery(100, 0)
-```
-
-If you pass `null` as the value for either of these variables, Apollo Kotlin sends `null` to the server _as the value of that variable_ instead of omitting it entirely.
-
-Although doing this can simplify your code in most cases, you might still need to omit variables for certain operations. To achieve this, you can allow optional variables on a case-by-case basis with the `@optional` directive:
-
-```graphql {1}
-query GetTodos($first: Int @optional, $offset: Int @optional) {
-  todos(first: $first, offset: $offset) {
-    id
-    text
-  }
-}
+val query = GetTodosQuery.Builder()
+               .first(100)
+               .offset(0)
+               .build()
 ```
 
-In this case, Apollo Kotlin generates code with `Optional` for only these specific variables.