#544 - Update docs and tests to reflect new strings-as-descriptions p…

…attern in new GraphQL SDL (#559)

* #64 - Update docs and tests to reflect new strings-as-descriptions pattern in new GraphQL SDL

* Make tests compatible with graphql v0.11

* Fix test errors

* Remove extra space

* Fix review comments

README.md

@@ -34,7 +34,10 @@ type Author {
   id: ID! # the ! means that every author object _must_ have an id
   firstName: String
   lastName: String
-  posts: [Post] # the list of Posts by this author
+  """
+  the list of Posts by this author
+  """
+  posts: [Post]
 }
 
 type Post {

docs/source/generate-schema.md

@@ -17,7 +17,10 @@ const typeDefs = `
     id: Int!
     firstName: String
     lastName: String
-    posts: [Post] # the list of Posts by this author
+    """
+    the list of Posts by this author
+    """
+    posts: [Post]
   }
 
   type Post {
@@ -279,19 +282,29 @@ const typeDefs = [`
 
 <h2 id="descriptions">Descriptions &amp; Deprecations</h2>
 GraphiQL has built-in support for displaying docstrings with markdown syntax. You can easily add docstrings to types, fields and arguments like below:
+
 ```
-# Description for the type
+"""
+Description for the type
+"""
 type MyObjectType {
-  # Description for field
+  """
+  Description for field
+  Supports multi-line description
+  """
   myField: String!
 
   otherField(
-    # Description for argument
+    """
+    Description for argument
+    """
     arg: Int
   )
 
   oldField(
-    # Description for argument
+    """
+    Description for argument
+    """
     arg: Int
   ) @deprecated(reason: "Use otherField instead.")
 }

docs/source/scalars.md

@@ -208,11 +208,8 @@ You can use it in your schema anywhere you could use a scalar:
 
 ```graphql
 type Query {
-  # As a return value
-  favoriteColor: AllowedColor
-
-  # As an argument
-  avatar(borderColor: AllowedColor): String
+  favoriteColor: AllowedColor # As a return value
+  avatar(borderColor: AllowedColor): String # As an argument
 }
 ```
 
@@ -249,11 +246,8 @@ const typeDefs = `
   }
 
   type Query {
-    # As a return value
-    favoriteColor: AllowedColor
-
-    # As an argument
-    avatar(borderColor: AllowedColor): String
+    favoriteColor: AllowedColor # As a return value
+    avatar(borderColor: AllowedColor): String # As an argument
   }
 `;
 

src/test/testMergeSchemas.ts

@@ -37,14 +37,20 @@ const testCombinations = [
   },
 ];
 
-const scalarTest = `
-  # Description of TestScalar.
+let scalarTest = `
+  """
+  Description of TestScalar.
+  """
   scalar TestScalar
 
-  # Description of AnotherNewScalar.
+  """
+  Description of AnotherNewScalar.
+  """
   scalar AnotherNewScalar
 
-  # A type that uses TestScalar.
+  """
+  A type that uses TestScalar.
+  """
   type TestingScalar {
     value: TestScalar
   }
@@ -54,31 +60,32 @@ const scalarTest = `
   }
 `;
 
-const enumTest = `
-# A type that uses an Enum.
-enum Color {
-  RED
-}
+let enumTest = `
+  """
+  A type that uses an Enum.
+  """
+  enum Color {
+    RED
+  }
 
-schema {
-  query: Query
-}
+  schema {
+    query: Query
+  }
 
-type Query {
-  color: Color
-}
+  type Query {
+    color: Color
+  }
 `;
 
-let graphql11compat = '';
-if (process.env.GRAPHQL_VERSION === '^0.11') {
-  graphql11compat = '{}';
-}
-
-const linkSchema = `
-  # A new type linking the Property type.
+let linkSchema = `
+  """
+  A new type linking the Property type.
+  """
   type LinkType {
     test: String
-    # The property.
+    """
+    The property.
+    """
     property: Property
   }
 
@@ -88,28 +95,36 @@ const linkSchema = `
 
 
   extend type Booking implements Node {
-    # The property of the booking.
+    """
+    The property of the booking.
+    """
     property: Property
   }
 
   extend type Property implements Node {
-    # A list of bookings.
+    """
+    A list of bookings.
+    """
     bookings(
-      # The maximum number of bookings to retrieve.
+      """
+      The maximum number of bookings to retrieve.
+      """
       limit: Int
     ): [Booking]
   }
 
   extend type Query {
     delegateInterfaceTest: TestInterface
     delegateArgumentTest(arbitraryArg: Int): Property
-    # A new field on the root query.
+    """
+    A new field on the root query.
+    """
     linkTest: LinkType
     node(id: ID!): Node
     nodes: [Node]
   }
 
-  extend type Customer implements Node ${graphql11compat}
+  extend type Customer implements Node
 `;
 
 const loneExtend = `
@@ -118,6 +133,77 @@ const loneExtend = `
   }
 `;
 
+if (process.env.GRAPHQL_VERSION === '^0.11') {
+  scalarTest = `
+    # Description of TestScalar.
+    scalar TestScalar
+
+    # Description of AnotherNewScalar.
+    scalar AnotherNewScalar
+
+    # A type that uses TestScalar.
+    type TestingScalar {
+      value: TestScalar
+    }
+
+    type Query {
+      testingScalar: TestingScalar
+    }
+  `;
+
+  enumTest = `
+    # A type that uses an Enum.
+    enum Color {
+      RED
+    }
+
+    schema {
+      query: Query
+    }
+
+    type Query {
+      color: Color
+    }
+  `;
+
+  linkSchema = `
+    # A new type linking the Property type.
+    type LinkType {
+      test: String
+      # The property.
+      property: Property
+    }
+
+    interface Node {
+      id: ID!
+    }
+
+    extend type Booking implements Node {
+      # The property of the booking.
+      property: Property
+    }
+
+    extend type Property implements Node {
+      # A list of bookings.
+      bookings(
+        # The maximum number of bookings to retrieve.
+        limit: Int
+      ): [Booking]
+    }
+
+    extend type Query {
+      delegateInterfaceTest: TestInterface
+      delegateArgumentTest(arbitraryArg: Int): Property
+      # A new field on the root query.
+      linkTest: LinkType
+      node(id: ID!): Node
+      nodes: [Node]
+    }
+
+    extend type Customer implements Node {}
+  `;
+}
+
 testCombinations.forEach(async combination => {
   describe('merging ' + combination.name, () => {
     let mergedSchema: GraphQLSchema,

src/test/testSchemaGenerator.ts

@@ -148,8 +148,10 @@ describe('generating schema from shorthand', () => {
   });
 
   it('can generate a schema', () => {
-    const shorthand = `
-      # A bird species
+    let shorthand = `
+      """
+      A bird species
+      """
       type BirdSpecies {
         name: String!,
         wingspan: Int
@@ -163,6 +165,23 @@ describe('generating schema from shorthand', () => {
       }
     `;
 
+    if (process.env.GRAPHQL_VERSION === '^0.11') {
+      shorthand = `
+        # A bird species
+        type BirdSpecies {
+          name: String!,
+          wingspan: Int
+        }
+        type RootQuery {
+          species(name: String!): [BirdSpecies]
+        }
+
+        schema {
+          query: RootQuery
+        }
+      `;
+    }
+
     const resolve = {
       RootQuery: {
         species() {