Support descriptions on variable definitions

libraries/apollo-ast/api/apollo-ast.api

@@ -851,14 +851,19 @@ public final class com/apollographql/apollo/ast/GQLUnionTypeExtension : com/apol
 public abstract class com/apollographql/apollo/ast/GQLValue : com/apollographql/apollo/ast/GQLNode {
 }
 
-public final class com/apollographql/apollo/ast/GQLVariableDefinition : com/apollographql/apollo/ast/GQLHasDirectives, com/apollographql/apollo/ast/GQLNamed, com/apollographql/apollo/ast/GQLNode {
+public final class com/apollographql/apollo/ast/GQLVariableDefinition : com/apollographql/apollo/ast/GQLDescribed, com/apollographql/apollo/ast/GQLHasDirectives, com/apollographql/apollo/ast/GQLNamed, com/apollographql/apollo/ast/GQLNode {
 	public fun <init> (Lcom/apollographql/apollo/ast/SourceLocation;Ljava/lang/String;Lcom/apollographql/apollo/ast/GQLType;Lcom/apollographql/apollo/ast/GQLValue;Ljava/util/List;)V
 	public synthetic fun <init> (Lcom/apollographql/apollo/ast/SourceLocation;Ljava/lang/String;Lcom/apollographql/apollo/ast/GQLType;Lcom/apollographql/apollo/ast/GQLValue;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Lcom/apollographql/apollo/ast/SourceLocation;Ljava/lang/String;Lcom/apollographql/apollo/ast/GQLType;Lcom/apollographql/apollo/ast/GQLValue;Ljava/util/List;Ljava/lang/String;)V
+	public synthetic fun <init> (Lcom/apollographql/apollo/ast/SourceLocation;Ljava/lang/String;Lcom/apollographql/apollo/ast/GQLType;Lcom/apollographql/apollo/ast/GQLValue;Ljava/util/List;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun copy (Lcom/apollographql/apollo/ast/SourceLocation;Ljava/lang/String;Lcom/apollographql/apollo/ast/GQLType;Lcom/apollographql/apollo/ast/GQLValue;Ljava/util/List;)Lcom/apollographql/apollo/ast/GQLVariableDefinition;
+	public final fun copy (Lcom/apollographql/apollo/ast/SourceLocation;Ljava/lang/String;Lcom/apollographql/apollo/ast/GQLType;Lcom/apollographql/apollo/ast/GQLValue;Ljava/util/List;Ljava/lang/String;)Lcom/apollographql/apollo/ast/GQLVariableDefinition;
 	public static synthetic fun copy$default (Lcom/apollographql/apollo/ast/GQLVariableDefinition;Lcom/apollographql/apollo/ast/SourceLocation;Ljava/lang/String;Lcom/apollographql/apollo/ast/GQLType;Lcom/apollographql/apollo/ast/GQLValue;Ljava/util/List;ILjava/lang/Object;)Lcom/apollographql/apollo/ast/GQLVariableDefinition;
+	public static synthetic fun copy$default (Lcom/apollographql/apollo/ast/GQLVariableDefinition;Lcom/apollographql/apollo/ast/SourceLocation;Ljava/lang/String;Lcom/apollographql/apollo/ast/GQLType;Lcom/apollographql/apollo/ast/GQLValue;Ljava/util/List;Ljava/lang/String;ILjava/lang/Object;)Lcom/apollographql/apollo/ast/GQLVariableDefinition;
 	public fun copyWithNewChildrenInternal (Lcom/apollographql/apollo/ast/NodeContainer;)Lcom/apollographql/apollo/ast/GQLNode;
 	public fun getChildren ()Ljava/util/List;
 	public final fun getDefaultValue ()Lcom/apollographql/apollo/ast/GQLValue;
+	public fun getDescription ()Ljava/lang/String;
 	public fun getDirectives ()Ljava/util/List;
 	public fun getName ()Ljava/lang/String;
 	public fun getSourceLocation ()Lcom/apollographql/apollo/ast/SourceLocation;

libraries/apollo-ast/api/apollo-ast.klib.api

@@ -1098,13 +1098,16 @@ final class com.apollographql.apollo.ast/GQLUnionTypeExtension : com.apollograph
     final fun writeInternal(com.apollographql.apollo.ast/SDLWriter) // com.apollographql.apollo.ast/GQLUnionTypeExtension.writeInternal|writeInternal(com.apollographql.apollo.ast.SDLWriter){}[0]
 }
 
-final class com.apollographql.apollo.ast/GQLVariableDefinition : com.apollographql.apollo.ast/GQLHasDirectives, com.apollographql.apollo.ast/GQLNamed, com.apollographql.apollo.ast/GQLNode { // com.apollographql.apollo.ast/GQLVariableDefinition|null[0]
+final class com.apollographql.apollo.ast/GQLVariableDefinition : com.apollographql.apollo.ast/GQLDescribed, com.apollographql.apollo.ast/GQLHasDirectives, com.apollographql.apollo.ast/GQLNamed, com.apollographql.apollo.ast/GQLNode { // com.apollographql.apollo.ast/GQLVariableDefinition|null[0]
     constructor <init>(com.apollographql.apollo.ast/SourceLocation? = ..., kotlin/String, com.apollographql.apollo.ast/GQLType, com.apollographql.apollo.ast/GQLValue?, kotlin.collections/List<com.apollographql.apollo.ast/GQLDirective>) // com.apollographql.apollo.ast/GQLVariableDefinition.<init>|<init>(com.apollographql.apollo.ast.SourceLocation?;kotlin.String;com.apollographql.apollo.ast.GQLType;com.apollographql.apollo.ast.GQLValue?;kotlin.collections.List<com.apollographql.apollo.ast.GQLDirective>){}[0]
+    constructor <init>(com.apollographql.apollo.ast/SourceLocation? = ..., kotlin/String, com.apollographql.apollo.ast/GQLType, com.apollographql.apollo.ast/GQLValue?, kotlin.collections/List<com.apollographql.apollo.ast/GQLDirective>, kotlin/String?) // com.apollographql.apollo.ast/GQLVariableDefinition.<init>|<init>(com.apollographql.apollo.ast.SourceLocation?;kotlin.String;com.apollographql.apollo.ast.GQLType;com.apollographql.apollo.ast.GQLValue?;kotlin.collections.List<com.apollographql.apollo.ast.GQLDirective>;kotlin.String?){}[0]
 
     final val children // com.apollographql.apollo.ast/GQLVariableDefinition.children|{}children[0]
         final fun <get-children>(): kotlin.collections/List<com.apollographql.apollo.ast/GQLNode> // com.apollographql.apollo.ast/GQLVariableDefinition.children.<get-children>|<get-children>(){}[0]
     final val defaultValue // com.apollographql.apollo.ast/GQLVariableDefinition.defaultValue|{}defaultValue[0]
         final fun <get-defaultValue>(): com.apollographql.apollo.ast/GQLValue? // com.apollographql.apollo.ast/GQLVariableDefinition.defaultValue.<get-defaultValue>|<get-defaultValue>(){}[0]
+    final val description // com.apollographql.apollo.ast/GQLVariableDefinition.description|{}description[0]
+        final fun <get-description>(): kotlin/String? // com.apollographql.apollo.ast/GQLVariableDefinition.description.<get-description>|<get-description>(){}[0]
     final val directives // com.apollographql.apollo.ast/GQLVariableDefinition.directives|{}directives[0]
         final fun <get-directives>(): kotlin.collections/List<com.apollographql.apollo.ast/GQLDirective> // com.apollographql.apollo.ast/GQLVariableDefinition.directives.<get-directives>|<get-directives>(){}[0]
     final val name // com.apollographql.apollo.ast/GQLVariableDefinition.name|{}name[0]
@@ -1115,6 +1118,7 @@ final class com.apollographql.apollo.ast/GQLVariableDefinition : com.apollograph
         final fun <get-type>(): com.apollographql.apollo.ast/GQLType // com.apollographql.apollo.ast/GQLVariableDefinition.type.<get-type>|<get-type>(){}[0]
 
     final fun copy(com.apollographql.apollo.ast/SourceLocation? = ..., kotlin/String = ..., com.apollographql.apollo.ast/GQLType = ..., com.apollographql.apollo.ast/GQLValue? = ..., kotlin.collections/List<com.apollographql.apollo.ast/GQLDirective> = ...): com.apollographql.apollo.ast/GQLVariableDefinition // com.apollographql.apollo.ast/GQLVariableDefinition.copy|copy(com.apollographql.apollo.ast.SourceLocation?;kotlin.String;com.apollographql.apollo.ast.GQLType;com.apollographql.apollo.ast.GQLValue?;kotlin.collections.List<com.apollographql.apollo.ast.GQLDirective>){}[0]
+    final fun copy(com.apollographql.apollo.ast/SourceLocation? = ..., kotlin/String = ..., com.apollographql.apollo.ast/GQLType = ..., com.apollographql.apollo.ast/GQLValue? = ..., kotlin.collections/List<com.apollographql.apollo.ast/GQLDirective> = ..., kotlin/String? = ...): com.apollographql.apollo.ast/GQLVariableDefinition // com.apollographql.apollo.ast/GQLVariableDefinition.copy|copy(com.apollographql.apollo.ast.SourceLocation?;kotlin.String;com.apollographql.apollo.ast.GQLType;com.apollographql.apollo.ast.GQLValue?;kotlin.collections.List<com.apollographql.apollo.ast.GQLDirective>;kotlin.String?){}[0]
     final fun copyWithNewChildrenInternal(com.apollographql.apollo.ast/NodeContainer): com.apollographql.apollo.ast/GQLNode // com.apollographql.apollo.ast/GQLVariableDefinition.copyWithNewChildrenInternal|copyWithNewChildrenInternal(com.apollographql.apollo.ast.NodeContainer){}[0]
     final fun writeInternal(com.apollographql.apollo.ast/SDLWriter) // com.apollographql.apollo.ast/GQLVariableDefinition.writeInternal|writeInternal(com.apollographql.apollo.ast.SDLWriter){}[0]
 }

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

@@ -165,7 +165,7 @@ class GQLOperationDefinition(
     val variableDefinitions: List<GQLVariableDefinition>,
     override val directives: List<GQLDirective>,
     val selections: List<GQLSelection>,
-    override val description: String?, // spec extension
+    override val description: String?,
 ) : GQLExecutableDefinition, GQLDescribed, GQLHasDirectives {
   @Suppress("DEPRECATION_ERROR")
   @Deprecated("Use selections directly", level = DeprecationLevel.ERROR)
@@ -1234,7 +1234,23 @@ class GQLVariableDefinition(
     val type: GQLType,
     val defaultValue: GQLValue?,
     override val directives: List<GQLDirective>,
-) : GQLNode, GQLNamed, GQLHasDirectives {
+    override val description: String?,
+) : GQLNode, GQLNamed, GQLDescribed, GQLHasDirectives {
+
+  constructor(
+      sourceLocation: SourceLocation? = null,
+      name: String,
+      type: GQLType,
+      defaultValue: GQLValue?,
+      directives: List<GQLDirective>,
+  ) : this(
+      sourceLocation = sourceLocation,
+      name = name,
+      type = type,
+      defaultValue = defaultValue,
+      directives = directives,
+      description = null
+  )
 
   override val children = listOfNotNull(defaultValue) + directives
 
@@ -1258,13 +1274,32 @@ class GQLVariableDefinition(
       type: GQLType = this.type,
       defaultValue: GQLValue? = this.defaultValue,
       directives: List<GQLDirective> = this.directives,
+      description: String? = this.description,
   ): GQLVariableDefinition {
     return GQLVariableDefinition(
         sourceLocation = sourceLocation,
         name = name,
         type = type,
         defaultValue = defaultValue,
         directives = directives,
+        description = description,
+    )
+  }
+
+  fun copy(
+      sourceLocation: SourceLocation? = this.sourceLocation,
+      name: String = this.name,
+      type: GQLType = this.type,
+      defaultValue: GQLValue? = this.defaultValue,
+      directives: List<GQLDirective> = this.directives,
+  ): GQLVariableDefinition {
+    return copy(
+        sourceLocation = sourceLocation,
+        name = name,
+        type = type,
+        defaultValue = defaultValue,
+        directives = directives,
+        description = null,
     )
   }
 

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

@@ -55,7 +55,6 @@ import com.apollographql.apollo.ast.GQLVariableDefinition
 import com.apollographql.apollo.ast.GQLVariableValue
 import com.apollographql.apollo.ast.ParserOptions
 import com.apollographql.apollo.ast.SourceLocation
-import kotlin.math.exp
 
 internal class Parser(
     src: String,
@@ -358,6 +357,7 @@ internal class Parser(
   }
 
   private fun parseVariableDefinition(): GQLVariableDefinition {
+    val description = expectOptionalToken<Token.String>()?.value
     val start = token
     expectToken<Token.Dollar>()
     val name = parseName()
@@ -374,7 +374,8 @@ internal class Parser(
         name = name,
         type = type,
         defaultValue = defaultValue,
-        directives = directives
+        directives = directives,
+        description = description,
     )
   }
 

libraries/apollo-compiler/api/apollo-compiler.api

@@ -1919,14 +1919,16 @@ public final class com/apollographql/apollo/compiler/ir/IrValue$Companion {
 
 public final class com/apollographql/apollo/compiler/ir/IrVariable {
 	public static final field Companion Lcom/apollographql/apollo/compiler/ir/IrVariable$Companion;
-	public fun <init> (Ljava/lang/String;Lcom/apollographql/apollo/compiler/ir/IrType;Lcom/apollographql/apollo/compiler/ir/IrValue;)V
+	public fun <init> (Ljava/lang/String;Lcom/apollographql/apollo/compiler/ir/IrType;Ljava/lang/String;Lcom/apollographql/apollo/compiler/ir/IrValue;)V
 	public final fun component1 ()Ljava/lang/String;
 	public final fun component2 ()Lcom/apollographql/apollo/compiler/ir/IrType;
-	public final fun component3 ()Lcom/apollographql/apollo/compiler/ir/IrValue;
-	public final fun copy (Ljava/lang/String;Lcom/apollographql/apollo/compiler/ir/IrType;Lcom/apollographql/apollo/compiler/ir/IrValue;)Lcom/apollographql/apollo/compiler/ir/IrVariable;
-	public static synthetic fun copy$default (Lcom/apollographql/apollo/compiler/ir/IrVariable;Ljava/lang/String;Lcom/apollographql/apollo/compiler/ir/IrType;Lcom/apollographql/apollo/compiler/ir/IrValue;ILjava/lang/Object;)Lcom/apollographql/apollo/compiler/ir/IrVariable;
+	public final fun component3 ()Ljava/lang/String;
+	public final fun component4 ()Lcom/apollographql/apollo/compiler/ir/IrValue;
+	public final fun copy (Ljava/lang/String;Lcom/apollographql/apollo/compiler/ir/IrType;Ljava/lang/String;Lcom/apollographql/apollo/compiler/ir/IrValue;)Lcom/apollographql/apollo/compiler/ir/IrVariable;
+	public static synthetic fun copy$default (Lcom/apollographql/apollo/compiler/ir/IrVariable;Ljava/lang/String;Lcom/apollographql/apollo/compiler/ir/IrType;Ljava/lang/String;Lcom/apollographql/apollo/compiler/ir/IrValue;ILjava/lang/Object;)Lcom/apollographql/apollo/compiler/ir/IrVariable;
 	public fun equals (Ljava/lang/Object;)Z
 	public final fun getDefaultValue ()Lcom/apollographql/apollo/compiler/ir/IrValue;
+	public final fun getDescription ()Ljava/lang/String;
 	public final fun getName ()Ljava/lang/String;
 	public final fun getType ()Lcom/apollographql/apollo/compiler/ir/IrType;
 	public fun hashCode ()I

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo/compiler/codegen/java/helpers/NamedType.kt

@@ -28,6 +28,7 @@ internal fun NamedType.toParameterSpec(context: JavaContext): ParameterSpec {
           context.layout.javaPropertyName(graphQlName),
       )
       .addAnnotations(irType.annotations)
+
       .build()
 }
 
@@ -42,7 +43,7 @@ internal fun IrInputField.toNamedType() = NamedType(
 internal fun IrVariable.toNamedType() = NamedType(
     graphQlName = name,
     type = type,
-    description = null,
+    description = description,
     deprecationReason = null,
 )
 

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo/compiler/codegen/java/operations/OperationBuilder.kt

@@ -272,6 +272,7 @@ internal class OperationBuilder(
         .map {
           val irType = context.resolver.resolveIrType(it.type)
           FieldSpec.builder(irType.withoutAnnotations(), context.layout.javaPropertyName(it.name))
+              .maybeAddDescription(it.description)
               .addAnnotations(irType.annotations)
               .build()
         }

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo/compiler/codegen/kotlin/helpers/NamedType.kt

@@ -101,7 +101,7 @@ internal fun IrInputField.toNamedType() = NamedType(
 internal fun IrVariable.toNamedType() = NamedType(
     graphQlName = name,
     type = type,
-    description = null,
+    description = description,
     deprecationReason = null,
     optInFeature = null,
 )
@@ -141,4 +141,4 @@ private fun List<NamedType>.toBuildFunSpec(context: KotlinContext, returnedClass
               .build()
       )
       .build()
-}
+}

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo/compiler/ir/IrOperations.kt

@@ -348,10 +348,11 @@ data class IrModelGroup(
 data class IrVariable(
     val name: String,
     val type: IrType,
+    val description: String?,
     /**
      * Used in `Operation.serializeVariables`
      */
-    val defaultValue: IrValue?
+    val defaultValue: IrValue?,
 )
 
 private val json = Json { classDiscriminator = "#class" }

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo/compiler/ir/IrOperationsBuilder.kt

@@ -374,6 +374,7 @@ internal class IrOperationsBuilder(
     return IrVariable(
         name = name,
         type = irType,
+        description = null,
         defaultValue = null
     )
   }
@@ -412,6 +413,7 @@ internal class IrOperationsBuilder(
     return IrVariable(
         name = name,
         type = irType,
+        description = description,
         defaultValue = defaultValue?.toIrValue()
     )
   }

libraries/apollo-compiler/src/test/graphql/com/example/antlr_tokens/TestOperation.graphql

@@ -1,6 +1,14 @@
 # A query that contains fields named as GraphQL keywords as well as a multiline string to make sure the parser
 # handles them correctly
-query TestQuery($operation: String) {
+"""
+The test query.
+"""
+query TestQuery(
+  """
+  The operation to perform.
+  """
+  $operation: String
+) {
   typeWithGraphQLKeywords {
     on
     null(fragment: $operation)