Add more documentation to @typePolicy (#6542)

* Add more documentation to `@typePolicy`

* Add a case for objects inheriting multiple keyfields

* oops

Author: martinbonnin

libraries/apollo-ast/src/commonMain/kotlin/com/apollographql/apollo/ast/internal/definitions.kt

@@ -1,7 +1,5 @@
 package com.apollographql.apollo.ast.internal
 
-import com.apollographql.apollo.annotations.ApolloInternal
-
 /**
  * This file contains several groups of GraphQL definitions we use during codegen:
  *
@@ -35,7 +33,42 @@ internal val kotlinLabsDefinitions_0_3 = """
   ""${'"'}
   directive @typePolicy(
       ""${'"'}
-      a selection set containing fields used to compute the cache key of an object. Order is important.
+      A selection set containing fields used to compute the cache key of an object. 
+      Nested selection sets are currently not supported. Order is important. 
+      
+      Key fields can be defined on interfaces. In that case, the key fields apply to all sub-types and sub-types are not allowed to define their own key fields.
+      If a type implements multiple interfaces with keyfields, the keyfields must match across all interfaces with keyfields.
+      
+      The key fields are automatically added to the operations by the compiler.
+      Aliased key fields are not recognized and the compiler adds a non-aliased version of the field if that happens.
+      If a type is queried through an interface/union, this may add fragments.
+
+      For an example, this query:
+      
+      ```graphql
+      query {
+        product {
+          price
+        }
+      }
+      ```
+      
+      is turned into this one after compilation: 
+      
+      ```graphql
+      query {
+        product {
+          ... on Book {
+            isbn
+          }
+          ... on Movie {
+            id
+          }
+          price
+        }
+      }
+      ```
+      
       ""${'"'}
       keyFields: String! = "",
       ""${'"'}