#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() {