add more documentation for data builders (#6088)

Author: martinbonnin

docs/source/migration/4.0.mdx

@@ -549,7 +549,9 @@ The [Android Studio plugin](../testing/android-studio-plugin#migration-helpers)
 
 ### Data builders
 
-With Apollo Kotlin 4, the syntax for using data builders for fragments is the same as for operations and [doesn't need the top level `buildFoo {}` wrapper](https://github.com/apollographql/apollo-kotlin/pull/4782):
+In Apollo Kotlin 3, using data builders with fragments required nesting the fields in a `buildFoo {}` block to determine the specific type returned. 
+
+In Apollo Kotlin 4, this is specified by using the first paramter of the `Data()` constructor function. This allows the syntax for using data builders with fragments to be the same as for operations:
 
 ```kotlin
 // Replace
@@ -567,6 +569,8 @@ val data = AnimalDetailsImpl.Data(Cat) {
 }
 ```
 
+See [data builders documentation](../testing/data-builders) for more details.
+
 ### Test builders are removed
 
 Test builders were an experimental feature that have been superseded by [data builders](../testing/data-builders), a simpler version that also plays nicer with custom scalars.

docs/source/testing/data-builders.mdx

@@ -195,3 +195,26 @@ fun test() {
   assertEquals(-1, data.hero.age)
 }
 ```
+
+## Using fragments 
+
+Because fragments may be defined on interfaces and unions, you need to explicit the concrete type you want to model. For an example, if you have an `Animal` interface, create a `Lion` fragment data using the following:
+
+```kotlin
+val data = AnimalDetailsImpl.Data(Lion) {
+  // you can access roar here
+  roar = "Grrrrr"
+}
+```
+
+Sometimes, you may want to test new types defined in your server that are not known to the client yet. To do so, use the abstract type (`Animal` here) as first parameter for the `Data()` constructor function. 
+
+In those cases, you need to specify the `__typename` of the returned object type explicitly: 
+
+```kotlin
+val data = AnimalDetailsImpl.Data(Animal) {
+  // the client doesn't know about this type yet, and you need to specify it explicitly
+  __typename = "Brontaroc"
+  species = "alien"
+}
+```