Improve ApolloEnum kdoc and mark related symbols experimental (#6677)

Author: martinbonnin

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo/compiler/codegen/kotlin/schema/EnumAsApolloEnumSupportBuilder.kt

@@ -38,6 +38,7 @@ internal class EnumAsApolloEnumSupportBuilder(
         fileName = simpleName,
         typeSpecs = listOf(
             TypeSpec.interfaceBuilder("ApolloEnum")
+                .addAnnotation(KotlinSymbols.ApolloExperimental)
                 .addTypeVariable(TypeVariableName("E"))
                 .addTypeVariable(TypeVariableName("K", ClassName(packageName, "KnownEnum").parameterizedBy(TypeVariableName("E"))))
                 .addProperty(PropertySpec.builder(rawValue, KotlinSymbols.String).build())
@@ -48,6 +49,7 @@ internal class EnumAsApolloEnumSupportBuilder(
         ),
         funSpecs = listOf(
             FunSpec.builder("knownOrDefault")
+                .addAnnotation(KotlinSymbols.ApolloExperimental)
                 .addModifiers(KModifier.INLINE)
                 .addTypeVariable(TypeVariableName("E", ClassName(packageName, "ApolloEnum").parameterizedBy(TypeVariableName("E"), TypeVariableName("K"))))
                 .addTypeVariable(TypeVariableName("K", ClassName(packageName, "KnownEnum").parameterizedBy(TypeVariableName("E"))).copy(reified = true))
@@ -57,6 +59,7 @@ internal class EnumAsApolloEnumSupportBuilder(
                 .addCode("return if (this is K) this else default(this)\n")
                 .build(),
             FunSpec.builder("knownOrNull")
+                .addAnnotation(KotlinSymbols.ApolloExperimental)
                 .addModifiers(KModifier.INLINE)
                 .addTypeVariable(TypeVariableName("E", ClassName(packageName, "ApolloEnum").parameterizedBy(TypeVariableName("E"), TypeVariableName("K"))))
                 .addTypeVariable(TypeVariableName("K", ClassName(packageName, "KnownEnum").parameterizedBy(TypeVariableName("E"))).copy(reified = true))

libraries/apollo-gradle-plugin/src/main/kotlin/com/apollographql/apollo/gradle/api/Service.kt

@@ -524,8 +524,63 @@ interface Service {
 
   /**
    * Whether to generate enums as ApolloEnum<E>.
+   * Generates GraphQL enums as a sealed interface hierarchy.
+   *
+   * This GraphQL enum:
+   * ```graphql
+   * enum Color {
+   *   BLUEBERRY,
+   *   CHERRY
+   *   CANDY
+   * }
+   * ```
+   *
+   *  Generates the following simplified Kotlin code:
+   *
+   * ```kotlin
+   * public interface ApolloEnum<E, K : KnownEnum<E>> {
+   *   public val rawValue: String
+   * }
+   *
+   * public sealed interface Color : ApolloEnum<Color, Color.__Known> {
+   *   override val rawValue: String
+   *
+   *   public data object BLUEBERRY : __Known {
+   *     override val rawValue: String = "BLUEBERRY"
+   *   }
+   *
+   *   public data object CHERRY : __Known {
+   *     override val rawValue: String = "CHERRY"
+   *   }
+   *
+   *   public data object CANDY : __Known {
+   *     override val rawValue: String = "CANDY"
+   *   }
+   *
+   *   public sealed interface __Known : Color, KnownEnum<Color> {
+   *     override val rawValue: String
+   *   }
+   *
+   *   public class __Unknown(
+   *     override val rawValue: String,
+   *   ) : Color
+   * }
+   * ```
+   *
+   * Using `ApolloEnum` allows to have an intermediate type for "known" enums so you can sanitize your enums
+   * and only deal with known enums if you want to:
+   *
+   * ```kotlin
+   * // this function only wants to deal with known colors
+   * fun doSomethingWith(color: Color.__Known) {
+   *   TODO()
+   * }
+   * val known = networkEnum.knownOrDefault { Color.CHERRY }
+   *
+   * doSomethingWith(known)
+   * ```
    *
-   * Experimental, see https://github.com/apollographql/apollo-kotlin/issues/6243.
+   * [generateApolloEnums] is experimental and only valid when [generateKotlinModels] is `true`.
    */
   @ApolloExperimental
   val generateApolloEnums: Property<Boolean>