RFC: Descriptions as strings.

As discussed in graphql/graphql-spec#90

This proposes replacing leading comment blocks as descriptions in the schema definition language with leading strings.

While I think there is some reduced ergonomics of using a string literal instead of a comment to write descriptions (unless perhaps you are accustomed to Python or Clojure), there are some compelling advantages:

* Descriptions are first-class in the AST of the schema definition language.
* Comments can remain "ignored" characters.
* No ambiguity between commented out regions and descriptions.

Specific to this reference implementation, since this is a breaking change and comment descriptions in the experimental SDL have fairly wide usage, I've left the comment description implementation intact and allow it to be enabled via an option. This should help with allowing upgrading with minimal impact on existing codebases and aid in automated transforms.

Author: leebyron

src/jsutils/dedent.js

@@ -8,16 +8,7 @@
  *  of patent rights can be found in the PATENTS file in the same directory.
  */
 
- /**
-  * fixes identation by removing leading spaces from each line
-  */
-function fixIdent(str: string): string {
-  const indent = /^\n?( *)/.exec(str)[1]; // figure out ident
-  return str
-    .replace(RegExp('^' + indent, 'mg'), '') // remove ident
-    .replace(/^\n*/m, '') //  remove leading newline
-    .replace(/ *$/, ''); // remove trailing spaces
-}
+import trimIndentation from './trimIndentation';
 
 /**
  * An ES6 string tag that fixes identation. Also removes leading newlines
@@ -46,5 +37,5 @@ export default function dedent(
     }
   }
 
-  return fixIdent(res);
+  return trimIndentation(res) + '\n';
 }

src/jsutils/trimIndentation.js

@@ -0,0 +1,68 @@
+/* @flow */
+/**
+ *  Copyright (c) 2017, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the BSD-style license found in the
+ *  LICENSE file in the root directory of this source tree. An additional grant
+ *  of patent rights can be found in the PATENTS file in the same directory.
+ */
+
+/**
+ * Removes leading identation from each line in a multi-line string.
+ *
+ * Note: this is similar to Python's docstring "trim" operation.
+ * https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation
+ */
+export default function trimIndentation(multiLine: string): string {
+  // Expand a multi-line string into independent lines.
+  const lines = multiLine.split('\n');
+
+  // Determine minimum indentation, not including the first line.
+  let minIndent;
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    const lineIndent = leadingWhitespace(line);
+    if (
+      lineIndent < line.length &&
+      (minIndent === undefined || lineIndent < minIndent)
+    ) {
+      minIndent = lineIndent;
+      if (minIndent === 0) {
+        break;
+      }
+    }
+  }
+
+  // Remove indentation, treating the first line specially.
+  const firstIndent = leadingWhitespace(lines[0]);
+  if (firstIndent) {
+    lines[0] = lines[0].slice(firstIndent);
+  }
+  if (minIndent) {
+    for (let i = 1; i < lines.length; i++) {
+      lines[i] = lines[i].slice(minIndent);
+    }
+  }
+
+  // Remove trailing and leading empty lines.
+  while (lines.length > 0 && lines[lines.length - 1].length === 0) {
+    lines.pop();
+  }
+  while (lines.length > 0 && lines[0].length === 0) {
+    lines.shift();
+  }
+
+  // Return a multi-line string.
+  return lines.join('\n');
+}
+
+function leadingWhitespace(str) {
+  let i = 0;
+  for (; i < str.length; i++) {
+    if (str[i] !== ' ' && str[i] !== '\t') {
+      break;
+    }
+  }
+  return i;
+}

src/language/__tests__/schema-kitchen-sink.graphql

@@ -10,6 +10,10 @@ schema {
   mutation: MutationType
 }
 
+"""
+This is a description
+of the `Foo` type.
+"""
 type Foo implements Bar {
   one: Type
   two(argument: InputType!): Type

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

@@ -96,6 +96,55 @@ type Hello {
     expect(printJson(doc)).to.equal(printJson(expected));
   });
 
+  it('parses type with description string', () => {
+    const doc = parse(`
+"Description"
+type Hello {
+  world: String
+}`);
+    expect(doc).to.containSubset({
+      kind: 'Document',
+      definitions: [
+        {
+          kind: 'ObjectTypeDefinition',
+          name: nameNode('Hello', { start: 20, end: 25 }),
+          description: {
+            kind: 'StringValue',
+            value: 'Description',
+            loc: { start: 1, end: 14 },
+          }
+        }
+      ],
+      loc: { start: 0, end: 45 },
+    });
+  });
+
+  it('parses type with description multi-line string', () => {
+    const doc = parse(`
+"""
+Description
+"""
+# Even with comments between them
+type Hello {
+  world: String
+}`);
+    expect(doc).to.containSubset({
+      kind: 'Document',
+      definitions: [
+        {
+          kind: 'ObjectTypeDefinition',
+          name: nameNode('Hello', { start: 60, end: 65 }),
+          description: {
+            kind: 'StringValue',
+            value: '\nDescription\n',
+            loc: { start: 1, end: 20 },
+          }
+        }
+      ],
+      loc: { start: 0, end: 85 },
+    });
+  });
+
   it('Simple extension', () => {
     const body = `
 extend type Hello {
@@ -130,6 +179,15 @@ extend type Hello {
     expect(printJson(doc)).to.equal(printJson(expected));
   });
 
+  it('Extension do not include descriptions', () => {
+    expect(() => parse(`
+      "Description"
+      extend type Hello {
+        world: String
+      }
+    `)).to.throw('Syntax Error GraphQL request (2:7)');
+  });
+
   it('Simple non-null type', () => {
     const body = `
 type Hello {

src/language/__tests__/schema-printer-test.js

@@ -56,6 +56,10 @@ describe('Printer', () => {
   mutation: MutationType
 }
 
+"""
+This is a description
+of the \`Foo\` type.
+"""
 type Foo implements Bar {
   one: Type
   two(argument: InputType!): Type

src/language/ast.js

@@ -398,13 +398,15 @@ export type TypeDefinitionNode =
 export type ScalarTypeDefinitionNode = {
   kind: 'ScalarTypeDefinition';
   loc?: Location;
+  description?: ?StringValueNode;
   name: NameNode;
   directives?: ?Array<DirectiveNode>;
 };
 
 export type ObjectTypeDefinitionNode = {
   kind: 'ObjectTypeDefinition';
   loc?: Location;
+  description?: ?StringValueNode;
   name: NameNode;
   interfaces?: ?Array<NamedTypeNode>;
   directives?: ?Array<DirectiveNode>;
@@ -414,6 +416,7 @@ export type ObjectTypeDefinitionNode = {
 export type FieldDefinitionNode = {
   kind: 'FieldDefinition';
   loc?: Location;
+  description?: ?StringValueNode;
   name: NameNode;
   arguments: Array<InputValueDefinitionNode>;
   type: TypeNode;
@@ -423,6 +426,7 @@ export type FieldDefinitionNode = {
 export type InputValueDefinitionNode = {
   kind: 'InputValueDefinition';
   loc?: Location;
+  description?: ?StringValueNode;
   name: NameNode;
   type: TypeNode;
   defaultValue?: ?ValueNode;
@@ -432,6 +436,7 @@ export type InputValueDefinitionNode = {
 export type InterfaceTypeDefinitionNode = {
   kind: 'InterfaceTypeDefinition';
   loc?: Location;
+  description?: ?StringValueNode;
   name: NameNode;
   directives?: ?Array<DirectiveNode>;
   fields: Array<FieldDefinitionNode>;
@@ -440,6 +445,7 @@ export type InterfaceTypeDefinitionNode = {
 export type UnionTypeDefinitionNode = {
   kind: 'UnionTypeDefinition';
   loc?: Location;
+  description?: ?StringValueNode;
   name: NameNode;
   directives?: ?Array<DirectiveNode>;
   types: Array<NamedTypeNode>;
@@ -448,6 +454,7 @@ export type UnionTypeDefinitionNode = {
 export type EnumTypeDefinitionNode = {
   kind: 'EnumTypeDefinition';
   loc?: Location;
+  description?: ?StringValueNode;
   name: NameNode;
   directives?: ?Array<DirectiveNode>;
   values: Array<EnumValueDefinitionNode>;
@@ -456,13 +463,15 @@ export type EnumTypeDefinitionNode = {
 export type EnumValueDefinitionNode = {
   kind: 'EnumValueDefinition';
   loc?: Location;
+  description?: ?StringValueNode;
   name: NameNode;
   directives?: ?Array<DirectiveNode>;
 };
 
 export type InputObjectTypeDefinitionNode = {
   kind: 'InputObjectTypeDefinition';
   loc?: Location;
+  description?: ?StringValueNode;
   name: NameNode;
   directives?: ?Array<DirectiveNode>;
   fields: Array<InputValueDefinitionNode>;
@@ -477,6 +486,7 @@ export type TypeExtensionDefinitionNode = {
 export type DirectiveDefinitionNode = {
   kind: 'DirectiveDefinition';
   loc?: Location;
+  description?: ?StringValueNode;
   name: NameNode;
   arguments?: ?Array<InputValueDefinitionNode>;
   locations: Array<NameNode>;

src/language/lexer.js

@@ -32,18 +32,24 @@ export function createLexer<TOptions>(
     token: startOfFileToken,
     line: 1,
     lineStart: 0,
-    advance: advanceLexer
+    advance: advanceLexer,
+    lookahead
   };
   return lexer;
 }
 
 function advanceLexer() {
-  let token = this.lastToken = this.token;
+  this.lastToken = this.token;
+  const token = this.token = this.lookahead();
+  return token;
+}
+
+function lookahead() {
+  let token = this.token;
   if (token.kind !== EOF) {
     do {
-      token = token.next = readToken(this, token);
+      token = token.next || (token.next = readToken(this, token));
     } while (token.kind === COMMENT);
-    this.token = token;
   }
   return token;
 }
@@ -79,6 +85,12 @@ export type Lexer<TOptions> = {
    * Advances the token stream to the next non-ignored token.
    */
   advance(): Token;
+
+  /**
+   * Looks ahead and returns the next non-ignored token, but does not change
+   * the Lexer's state.
+   */
+  lookahead(): Token;
 };
 
 // Each kind of token.