suggestions for executable definition descriptions

src/__testUtils__/kitchenSinkQuery.ts

@@ -1,5 +1,10 @@
 export const kitchenSinkQuery: string = String.raw`
-query queryName($foo: ComplexType, $site: Site = MOBILE) @onQuery {
+"Query description"
+query queryName(
+  "Very complex variable"
+  $foo: ComplexType,
+  $site: Site = MOBILE
+) @onQuery {
   whoever123is: node(id: [123, 456]) {
     id
     ... on User @onInlineFragment {
@@ -44,6 +49,9 @@ subscription StoryLikeSubscription(
   }
 }
 
+"""
+  Fragment description
+"""
 fragment frag on Friend @onFragmentDefinition {
   foo(
     size: $size

src/language/__tests__/parser-test.ts

@@ -1,4 +1,4 @@
-import { expect } from 'chai';
+import { assert, expect } from 'chai';
 import { describe, it } from 'mocha';
 
 import { dedent } from '../../__testUtils__/dedent';
@@ -57,6 +57,15 @@ describe('Parser', () => {
       locations: [{ line: 1, column: 1 }],
     });
 
+    // Throws on first error, the unexpected description.
+    expectSyntaxError(`
+      "Unexpected description"
+      notAnOperation Foo { field }
+    `).to.deep.include({
+      message: 'Syntax Error: Unexpected description, only GraphQL definitions support descriptions.',
+      locations: [{ line: 2, column: 7 }],
+    });
+
     expectSyntaxError('...').to.deep.include({
       message: 'Syntax Error: Unexpected "...".',
       locations: [{ line: 1, column: 1 }],
@@ -259,6 +268,7 @@ describe('Parser', () => {
         {
           kind: Kind.OPERATION_DEFINITION,
           loc: { start: 0, end: 40 },
+          description: undefined,
           operation: 'query',
           name: undefined,
           variableDefinitions: [],
@@ -349,6 +359,7 @@ describe('Parser', () => {
         {
           kind: Kind.OPERATION_DEFINITION,
           loc: { start: 0, end: 29 },
+          description: undefined,
           operation: 'query',
           name: undefined,
           variableDefinitions: [],
@@ -657,4 +668,99 @@ describe('Parser', () => {
       });
     });
   });
+
+  describe('operation and variable definition descriptions', () => {
+    it('parses operation with description and variable descriptions', () => {
+      const result = parse(dedent`
+        "Operation description"
+        query myQuery(
+          "Variable a description"
+          $a: Int,
+          """Variable b\nmultiline description"""
+          $b: String
+        ) {
+          field(a: $a, b: $b)
+        }
+      `);
+
+      const opDef = result.definitions[0];
+      assert(opDef.kind === Kind.OPERATION_DEFINITION);
+
+      expect(opDef.description?.value).to.equal('Operation description');
+      expect(opDef.name?.value).to.equal('myQuery');
+      expect(opDef.variableDefinitions?.[0].description?.value).to.equal(
+        'Variable a description',
+      );
+      expect(opDef.variableDefinitions?.[0].description?.block).to.equal(false);
+      expect(opDef.variableDefinitions?.[1].description?.value).to.equal(
+        'Variable b\nmultiline description',
+      );
+      expect(opDef.variableDefinitions?.[1].description?.block).to.equal(true);
+      expect(opDef.variableDefinitions?.[0].variable.name.value).to.equal('a');
+      expect(opDef.variableDefinitions?.[1].variable.name.value).to.equal('b');
+
+      const typeA = opDef.variableDefinitions?.[0].type;
+      assert(typeA?.kind === Kind.NAMED_TYPE);
+
+      expect(typeA.name.value).to.equal('Int');
+
+      const typeB = opDef.variableDefinitions?.[1].type;
+      assert(typeB?.kind === Kind.NAMED_TYPE);
+
+      expect(typeB.name.value).to.equal('String');
+    });
+
+    it('parses variable definition with description, default value, and directives', () => {
+      const result = parse(dedent`
+        query (
+          "desc"
+          $foo: Int = 42 @dir
+        ) {
+          field(foo: $foo)
+        }
+      `);
+
+      const opDef = result.definitions[0];
+      assert(opDef.kind === Kind.OPERATION_DEFINITION);
+      const varDef = opDef.variableDefinitions?.[0];
+      expect(varDef?.description?.value).to.equal('desc');
+      expect(varDef?.variable.name.value).to.equal('foo');
+
+      assert(varDef?.type.kind === Kind.NAMED_TYPE);
+      expect(varDef.type.name.value).to.equal('Int');
+
+      assert(varDef?.defaultValue?.kind === Kind.INT);
+      expect(varDef.defaultValue.value).to.equal('42');
+
+      expect(varDef?.directives?.[0].name.value).to.equal('dir');
+    });
+
+    it('parses fragment with variable description (legacy)', () => {
+      const result = parse('fragment Foo("desc" $foo: Int) on Bar { baz }', {
+        allowLegacyFragmentVariables: true,
+      });
+      const fragDef = result.definitions[0]
+      assert(fragDef.kind === Kind.FRAGMENT_DEFINITION);
+
+      const varDef = fragDef.variableDefinitions?.[0];
+      expect(varDef?.description?.value).to.equal('desc');
+      expect(varDef?.variable.name.value).to.equal('foo');
+
+      assert(varDef?.type.kind === Kind.NAMED_TYPE);
+      expect(varDef.type.name.value).to.equal('Int');
+    });
+
+    it('produces sensible error for description on shorthand query', () => {
+      expect(() =>
+        parse(dedent`
+          "This is a description"
+          {
+            field
+          }
+        `),
+      ).to.throw(
+        'Syntax Error: Unexpected description, shorthand queries do not support descriptions.',
+      );
+    });
+  });
 });

src/language/__tests__/printer-test.ts

@@ -44,19 +44,21 @@ describe('Printer: Query document', () => {
     `);
 
     const queryASTWithArtifacts = parse(
-      'query ($foo: TestType) @testDirective { id, name }',
+      '"Query description" query ($foo: TestType) @testDirective { id, name }',
     );
     expect(print(queryASTWithArtifacts)).to.equal(dedent`
+      "Query description"
       query ($foo: TestType) @testDirective {
         id
         name
       }
     `);
 
     const mutationASTWithArtifacts = parse(
-      'mutation ($foo: TestType) @testDirective { id, name }',
+      '"Mutation description" mutation ($foo: TestType) @testDirective { id, name }',
     );
     expect(print(mutationASTWithArtifacts)).to.equal(dedent`
+      "Mutation description"
       mutation ($foo: TestType) @testDirective {
         id
         name
@@ -66,10 +68,13 @@ describe('Printer: Query document', () => {
 
   it('prints query with variable directives', () => {
     const queryASTWithVariableDirective = parse(
-      'query ($foo: TestType = {a: 123} @testDirective(if: true) @test) { id }',
+      'query ("Variable description" $foo: TestType = {a: 123} @testDirective(if: true) @test) { id }',
     );
     expect(print(queryASTWithVariableDirective)).to.equal(dedent`
-      query ($foo: TestType = {a: 123} @testDirective(if: true) @test) {
+      query (
+      "Variable description"
+      $foo: TestType = {a: 123} @testDirective(if: true) @test
+      ) {
         id
       }
     `);
@@ -110,6 +115,19 @@ describe('Printer: Query document', () => {
     `);
   });
 
+  it('prints fragment', () => {
+    const printed = print(
+      parse('"Fragment description" fragment Foo on Bar { baz }'),
+    );
+
+    expect(printed).to.equal(dedent`
+      "Fragment description"
+      fragment Foo on Bar {
+        baz
+      }
+    `);
+  });
+
   it('Legacy: prints fragment with variable directives', () => {
     const queryASTWithVariableDirective = parse(
       'fragment Foo($foo: TestType @test) on TestType @testDirective { id }',
@@ -150,7 +168,12 @@ describe('Printer: Query document', () => {
 
     expect(printed).to.equal(
       dedentString(String.raw`
-      query queryName($foo: ComplexType, $site: Site = MOBILE) @onQuery {
+      "Query description"
+      query queryName(
+      "Very complex variable"
+      $foo: ComplexType
+      $site: Site = MOBILE
+      ) @onQuery {
         whoever123is: node(id: [123, 456]) {
           id
           ... on User @onInlineFragment {
@@ -192,6 +215,7 @@ describe('Printer: Query document', () => {
         }
       }
 
+      """Fragment description"""
       fragment frag on Friend @onFragmentDefinition {
         foo(
           size: $size

src/language/__tests__/schema-parser-test.ts

@@ -331,7 +331,7 @@ describe('Schema Parser', () => {
       }
     `).to.deep.equal({
       message:
-        'Syntax Error: Unexpected description, descriptions are supported only on type definitions.',
+        'Syntax Error: Unexpected description, only GraphQL definitions support descriptions.',
       locations: [{ line: 2, column: 7 }],
     });
 
@@ -353,7 +353,7 @@ describe('Schema Parser', () => {
       }
     `).to.deep.equal({
       message:
-        'Syntax Error: Unexpected description, descriptions are supported only on type definitions.',
+        'Syntax Error: Unexpected description, only GraphQL definitions support descriptions.',
       locations: [{ line: 2, column: 7 }],
     });
 

src/language/__tests__/visitor-test.ts

@@ -539,9 +539,13 @@ describe('Visitor', () => {
     expect(visited).to.deep.equal([
       ['enter', 'Document', undefined, undefined],
       ['enter', 'OperationDefinition', 0, undefined],
+      ['enter', 'StringValue', 'description', 'OperationDefinition'],
+      ['leave', 'StringValue', 'description', 'OperationDefinition'],
       ['enter', 'Name', 'name', 'OperationDefinition'],
       ['leave', 'Name', 'name', 'OperationDefinition'],
       ['enter', 'VariableDefinition', 0, undefined],
+      ['enter', 'StringValue', 'description', 'VariableDefinition'],
+      ['leave', 'StringValue', 'description', 'VariableDefinition'],
       ['enter', 'Variable', 'variable', 'VariableDefinition'],
       ['enter', 'Name', 'name', 'Variable'],
       ['leave', 'Name', 'name', 'Variable'],
@@ -793,6 +797,8 @@ describe('Visitor', () => {
       ['leave', 'SelectionSet', 'selectionSet', 'OperationDefinition'],
       ['leave', 'OperationDefinition', 2, undefined],
       ['enter', 'FragmentDefinition', 3, undefined],
+      ['enter', 'StringValue', 'description', 'FragmentDefinition'],
+      ['leave', 'StringValue', 'description', 'FragmentDefinition'],
       ['enter', 'Name', 'name', 'FragmentDefinition'],
       ['leave', 'Name', 'name', 'FragmentDefinition'],
       ['enter', 'NamedType', 'typeCondition', 'FragmentDefinition'],

src/language/ast.ts

@@ -198,12 +198,19 @@ export const QueryDocumentKeys: {
 
   Document: ['definitions'],
   OperationDefinition: [
+    'description',
     'name',
     'variableDefinitions',
     'directives',
     'selectionSet',
   ],
-  VariableDefinition: ['variable', 'type', 'defaultValue', 'directives'],
+  VariableDefinition: [
+    'description',
+    'variable',
+    'type',
+    'defaultValue',
+    'directives',
+  ],
   Variable: ['name'],
   SelectionSet: ['selections'],
   Field: ['alias', 'name', 'arguments', 'directives', 'selectionSet'],
@@ -212,6 +219,7 @@ export const QueryDocumentKeys: {
   FragmentSpread: ['name', 'directives'],
   InlineFragment: ['typeCondition', 'directives', 'selectionSet'],
   FragmentDefinition: [
+    'description',
     'name',
     // Note: fragment variable definitions are deprecated and will removed in v17.0.0
     'variableDefinitions',
@@ -317,6 +325,7 @@ export type ExecutableDefinitionNode =
 export interface OperationDefinitionNode {
   readonly kind: Kind.OPERATION_DEFINITION;
   readonly loc?: Location;
+  readonly description?: StringValueNode;
   readonly operation: OperationTypeNode;
   readonly name?: NameNode;
   readonly variableDefinitions?: ReadonlyArray<VariableDefinitionNode>;
@@ -334,6 +343,7 @@ export { OperationTypeNode };
 export interface VariableDefinitionNode {
   readonly kind: Kind.VARIABLE_DEFINITION;
   readonly loc?: Location;
+  readonly description?: StringValueNode;
   readonly variable: VariableNode;
   readonly type: TypeNode;
   readonly defaultValue?: ConstValueNode;
@@ -398,6 +408,7 @@ export interface InlineFragmentNode {
 export interface FragmentDefinitionNode {
   readonly kind: Kind.FRAGMENT_DEFINITION;
   readonly loc?: Location;
+  readonly description?: StringValueNode;
   readonly name: NameNode;
   /** @deprecated variableDefinitions will be removed in v17.0.0 */
   readonly variableDefinitions?: ReadonlyArray<VariableDefinitionNode>;