[📖 docs] Add a note about addTypename in the cache docs (#5687)

* add a note about typename in declarative cache

* add a link to the kdoc

docs/source/caching/declarative-ids.mdx

@@ -47,7 +47,11 @@ We can add the following definition to an `extra.graphqls` file in the same dire
 extend type Book @typePolicy(keyFields: "id")
 ```
 
-Apollo Kotlin now knows to use the `id` field of a `Book` type to generate its cache ID.
+Apollo Kotlin now knows to use the `id` field of a `Book` type to generate its cache ID. A cache record may now look like
+
+```
+"Book:bk123": {"id": "bk123", "title": "Les guerriers du silence", "author": "ApolloCacheReference{favoriteBook.author}"}
+```
 
 You can specify _multiple_ key fields for an object if they're all required to uniquely identify a particular cache entry:
 
@@ -56,13 +60,29 @@ You can specify _multiple_ key fields for an object if they're all required to u
 extend type Author @typePolicy(keyFields: "firstName lastName")
 ```
 
-In this case, the cache ID for an `Author` object includes the values of both its `firstName` and `lastName` fields.
+In this case, the cache ID for an `Author` object includes the values of both its `firstName` and `lastName` fields:
+
+```
+"Author:PierreBordage": {"id": "au456", "firstName": "Pierre", "lastName": "Bordage"}
+```
 
 > All of an object type's key fields must return a [scalar type](https://www.apollographql.com/docs/apollo-server/schema/schema/#scalar-types).
 
 > Note that the **key fields** specified this way will automatically be added during code generation to selections on the object type, since they are always needed to identify the object in the cache.
 > This means you don't need to include them in your queries.
 
+## Adding `__typename` to your operations
+
+In addition to the key fields, the declarative cache requires the `__typename` of each object by default. These typenames are not included by default as they make query larger for non-cache users. To avoid cache misses, add `__typename` to every selection using [addTypename](https://www.apollographql.com/docs/kotlin/kdoc/apollo-gradle-plugin-external/com.apollographql.apollo3.gradle.api/-service/add-typename.html):
+
+```kotlin
+apollo {
+  service("service") {
+    addTypename.set("always")
+  }
+}
+```
+
 ## `@fieldPolicy`
 
 The `@fieldPolicy` directive enables you to specify an object's cache ID from the values of **key arguments** you provide to a particular field. This enables you to identify an object in your cache _before_ sending a network request, potentially enabling you to skip the request entirely.

docs/source/caching/programmatic-ids.mdx

@@ -55,11 +55,13 @@ You can also use the current object's typename to use _different_ cache ID gener
 
 Note that for cache ID generation to work, your GraphQL operations must return whatever fields your custom code relies on (such as `id` above). If a query does not return a required field, the cache ID will be inconsistent, resulting in data duplication.
 Also, using `context.field.type.leafType().name` yields the typename of the Union as opposed to the expected runtime value of Union received in the response. Instead querying for the `__typename` is safer.
-To make sure `__typename` is included in all operations set the `adTypename` gradle config:
+To make sure `__typename` is included in all operations set the [addTypename](https://www.apollographql.com/docs/kotlin/kdoc/apollo-gradle-plugin-external/com.apollographql.apollo3.gradle.api/-service/add-typename.html) gradle config:
+
 ```
 apollo {
-  addTypename.set("always")
-  //
+  service("service") {
+    addTypename.set("always")
+  }
 }
 ```