Update the docs to reflect the newest changes. (#839)

Author: Cryt1c

doc/README.md

@@ -10,7 +10,7 @@ Anyone who wants to get JSON data out of Drupal.
 
 A few examples of where the GraphQL module could be used:
 
-* Decoupled Drupal applications with a javascript front-end \(React, Angular, Ember, etc\), 
+* Decoupled Drupal applications with a javascript front-end \(React, Angular, Ember, etc\),
 * Twig Templates \(Drupal theming\)
 * Mobile applications that need a persistent data store
 * IOT data storage
@@ -23,14 +23,14 @@ This trade-off does come with costs mostly around ease of use, where in the 3.x
 
 ## Hello World \(Quick Start\)
 
-1. Familiarize yourself with the GraphQL language. The official GraphQL docs are very well written. 
+1. Familiarize yourself with the GraphQL language. The official GraphQL docs are very well written.
 
    [http://graphql.org/learn/](http://graphql.org/learn/)
 
 2. Install the module and enable GraphQL.
-3. Login and navigate to `/admin/config/graphql` create a new server. You can use the Test schema that comes with the module to try out using GraphQL for the first time before making your own schema. Create the server and specify and endpoint such as `/graphql`. After creating the server click on `explorer` and this should bring you to the Graphiql explorer.
+3. Login and navigate to `/admin/config/graphql` create a new server. You can use the "Example schema" that comes with the graphql_examples module (comes with the graphql module but needs to be enabled separately) to try out using GraphQL for the first time before making your own schema. Create a server and specify an endpoint such as `/graphql`. After creating the server click on `explorer` and this should bring you to the Graphiql explorer.
 
-For a query to work first you need to make an Article node. Create one with the title "Hello GraphQL" and save it.
+To be able to query something you first have to create an Article in the Drupal backend.
 
 4. **Read the comments** and then enter the following query in the left pane:
 
@@ -59,6 +59,6 @@ For a query to work first you need to make an Article node. Create one with the
 
 **NOTES:**
 
-* The GraphiQL explorer, included with the module, is your friend, it’s amazing. You will most likely use the GraphiQL explorer to build and test more complicated queries. 
-* GraphQL is introspective, meaning that the entire schema \(data model\) is known up front. This is important as it allows tools like GraphiQL to implement autocompletion. 
+* The GraphiQL explorer, included with the module, is your friend, it’s amazing. You will most likely use the GraphiQL explorer to build and test more complicated queries.
+* GraphQL is introspective, meaning that the entire schema \(data model\) is known up front. This is important as it allows tools like GraphiQL to implement autocompletion.
 * You can use GraphiQL to explore your way through the data and configuration, once you know the basic GraphQL syntax. You can use the tab key in the explorer like you would with autocompletion or intellisense in modern IDEs.

doc/producers/README.md

@@ -38,7 +38,7 @@ The following code is an example of how a data producer for a creator field on t
 
 Essentially this is what you need to do every time you want to make a field available in the schema. We tell Drupal where and how to get the data and specify where this maps to.
 
-This particular resolver uses the `property_path` data producer that comes with the GraphQL module. It's one of the most common ones and you will find yourself using often to resolve any kind of property on an entity. The module includes a lot more which we will see in the "Built in Data Producers" section.
+This particular resolver uses the `property_path` data producer that comes with the GraphQL module. It's one of the most common ones and you will find yourself using it often to resolve any kind of property on an entity. The module includes a lot more which we will see in the "Built in Data Producers" section.
 
 ## Notes
 

doc/queries/README.md

@@ -1,10 +1,10 @@
 # Queries
 
-Queries in Drupal GraphQL work by combining data producers in order to resolve values of fields added to the schema. As we have already seen in previous examples its in most cases a 2-step process of first adding the schema information and then resolving whatever we added in the schema to actual data.
+Queries in the graphql module work by combining data producers in order to resolve values of fields that are added to the schema. As we have already seen in previous examples, it's in most cases a 2-step process of first adding the schema information and then resolving whatever we added in the schema to actual data.
 
-In this section we will learn how to use the built-in data producers to resolve common data required by most websites or application that will use GraphQL. The code with all the demo queries and mutations in these docs can be found in [this repository](https://github.com/joaogarin/mydrupalgql).
+In this section we will learn how to use the built-in data producers to resolve common data as it is required by most web application that use GraphQL. The code with all the demo queries and mutations in these docs can be found in [this repository](https://github.com/joaogarin/mydrupalgql).
 
-Lets quickly look again at a simple field on an existing entity like the "Article" content type that comes with Drupal. First we make that field available in the schema, lets take as an example the title : 
+Let's take a look at a simple field on an existing entity like the "Article" content type that comes with Drupal. As a first step, we include this field in the schema. Let's take the title as an example:
 
 ```
 type Article implements NodeInterface {
@@ -14,9 +14,9 @@ type Article implements NodeInterface {
 }
 ```
 
-We now need to resolve the title field via data producer provided by the module `entity_label` which will give us the label of an entity : 
+We now need to resolve the title field via a data producer which is already provided by the `entity_label` module. This will give us the label of an entity:
 
-```php 
+```php
     $registry->addFieldResolver('Article', 'title',
       $builder->produce('entity_label', [
         'mapping' => [
@@ -26,15 +26,17 @@ We now need to resolve the title field via data producer provided by the module
     );
 ```
 
-We now can run a query like this : 
+We can now run a query like this:
 
 ```graphql
-article(id:1) {
-    title
+query {
+  article(id:1) {
+      title
+  }
 }
 ```
 
-and get something like : 
+and get the following result:
 
 ```json
 {
@@ -46,4 +48,4 @@ and get something like :
 }
 ```
 
-Next we will look at more complex scenarios like loading custom fields, menus and menu links, taxonomies and other kind of fields.
+Next, we will look at more complex scenarios like loading custom fields, menus, menu links, taxonomies and other kind of fields.

doc/queries/menus.md

@@ -1,10 +1,10 @@
 # Querying menus
 
-Another common use case you will run need is to query a menu, this is particularly useful for use cases where you will want to control or add items via the backend in the drupal administration interface.
+Another common use case you will often need is to query a menu. This is particularly useful for use cases where you will want to control or add items via the backend in the Drupal administration interface.
 
 ## Add the schema declaration
 
-The first step as seen in the introduction is to add the types and fields in the schema. We can do this directly in the schema string in your own schema implementation.
+The first step, as seen in the introduction, is to add the types and fields in the schema. We can do this directly in the schema string in your own schema implementation (`src/Plugin/GraphQL/Schema/SdlSchemaMyDrupalGql.php`).
 
 ```
 ...
@@ -124,4 +124,4 @@ To add the resolvers we go to our schema implementation and call the appropriate
   }
 ```
 
-As we see here we need to really provide all the fields with a resolver in order to have the data available, this can seem a bit unnecessary at first but its a crucial step towards a cleaner API. In this case we resolve the `menu` inside the `Query` type and from there we start resolving each field from `Menu` and also `MenuItem`.
+As we can see here we need to really provide all the fields with a resolver in order to have the data available, this can seem a bit unnecessary at first but it's a crucial step towards a cleaner API. In this case, we resolve the `menu` inside the `Query` type and from there we can start resolving each field from `Menu` and also `MenuItem`.

doc/queries/nodes.md

@@ -1,12 +1,12 @@
 # Querying nodes
 
-One common scenarios you will run into is to query a node together with certain fields. We have seen already a couple of things that can give a good overview on how to do this, but lets take an example again of the "Article" type and get some fields out of it like the `id` and `label` but also a custom field `creator` which is just a normal text field in this content type.
+A common scenario into which you will run often is to query a node together with certain field. We have already seen a couple of things that can give a good overview on how to do this. Let's take our example of the "Article" type again and query some fields like the `id`, the `label` but also the custom field `creator` which is just a normal text field.
 
-Before this make sure to read the introduction and how to add you own custom schema, only after that you can start adding resolvers and extending your DSL with your own types.
+Before you start, make sure to read the introduction and how to add a custom schema, only after that you should start adding resolvers and extending your schema with your own types.
 
 ## Add the schema declaration
 
-The first step as seen in the introduction is to add the types and fields in the schema. We can do this directly in the schema string in your own schema implementation.
+The first step, as seen in the introduction, is to add the types and fields in the schema. You can add this directly into schema string in your own schema implementation (`src/Plugin/GraphQL/Schema/SdlSchemaMyDrupalGql.php`).
 
 ```
 schema {
@@ -31,7 +31,8 @@ interface NodeInterface {
     id: Int!
 }
 ```
-Now we have an article in the schema with 3 fields `id`, `label` and our custom field `creator`. We can start adding resolvers for each of them.
+
+Now we have an "Article" type in the schema with three fields `id`, `label` and our custom field `creator`. The next step is to add resolvers for each of them.
 
 ## Adding resolvers
 

doc/queries/references.md

@@ -1,12 +1,12 @@
 # Querying entity references
 
-Continuing on our previous example lets add a new field that in this case is an entity reference for example for a taxonomy term.
+Continuing on our previous example let's add a new field that is an entity reference for a taxonomy term.
 
-Again we need to do similar steps to add the field to the schema and add its resolver.
+We again need to do similar steps to add the field to the schema and add its resolver.
 
 ## Add the schema declaration
 
-The first step as seen in the introduction is to add the types and fields in the schema. We can do this directly in the schema string in your own schema implementation.
+The first step as seen in the introduction is to add the types and fields in the schema. We can do this directly in the schema string in your own schema implementation (`src/Plugin/GraphQL/Schema/SdlSchemaMyDrupalGql.php`).
 
 ```
 ...
@@ -26,9 +26,9 @@ type TagTerm {
 ...
 
 ```
-Now we have an article that also has a custom entity reference field to a taxonomy category (the field name in Drupal is `field_tags`) and we make a new type `TagTerm` that has the necessary information about this term.
+Now we have an article that also has a custom entity reference field to a taxonomy term (the field name in Drupal is `field_tags`) and we make a new type `TagTerm` that has the necessary information about this term.
 
-We will need to resolve not only the `tags` field but also the `id` and `name` of the term. 
+We will need to resolve not only the `tags` field but also the `id` and `name` of the term.
 
 ## Adding resolvers
 
@@ -39,9 +39,9 @@ Again inside the `getResolverRegistry` method :
    * {@inheritdoc}
    */
   protected function getResolverRegistry() {
-    
+
     ...
-    
+
     $registry->addFieldResolver('Article', 'tags',
       $builder->produce('entity_reference', [
         'mapping' => [
@@ -69,4 +69,4 @@ Again inside the `getResolverRegistry` method :
   }
 ```
 
-Notice how again we are using common Data producers provided by the module like `entity_id`, `entity_label` and also `entity_reference` in this case.
+Notice how again we are using common data producers provided by the module like `entity_id`, `entity_label` and also `entity_reference` in this case.

doc/queries/routes.md

@@ -1,12 +1,12 @@
 # Querying routes
 
-A very powerful feature of Drupal is the ability to manage paths in entities and using path alias to manage clean URL's. We can leverage Data producers provided by the GraphQL module to get that data out of Drupal.
+A very powerful feature of Drupal is the ability to manage paths in entities and using path aliases to manage clean URL's. We can leverage data producers provided by the graphql module to query these paths from Drupal.
 
 In this section we will look at how we can load a node from it's URL.
 
 ## Add the schema declaration
 
-The first step as seen in the introduction is to add the types and fields in the schema. We can do this directly in the schema string in your own schema implementation.
+The first step, as seen in the introduction, is to add the types and fields in the schema. We can do this directly in the schema string in your own schema implementation (`src/Plugin/GraphQL/Schema/SdlSchemaMyDrupalGql.php`).
 
 ```
 ...
@@ -29,7 +29,7 @@ interface NodeInterface {
 
 ```
 
-In this schema we can see that we can query a node by its route, that takes a parameter called "path". We also (similar to the test schema that comes with the module) have a NodeInterface and a Article type that implements that interface. That means our "Article" will be available inside a fragment in the NodeInterface type.
+In this schema we can see that we can query a node by its route, that takes a parameter called "path". We also (similar to the test schema that comes with the module) have a "NodeInterface" and an "Article" type that implements that interface. That means our "Article" will be available inside a fragment in the NodeInterface type.
 
 ## Adding resolvers
 
@@ -61,12 +61,12 @@ To add the resolvers we go to our schema implementation and call the appropriate
   }
 ```
 
-Here we take advantage of the `compose` method inside our resolver builder object that allows chaining multiple producers together. This is a very useful technique, that will be very useful when dealing with more complex scenarios.
+Here we take advantage of the `compose` method inside our resolver builder object that allows chaining multiple producers together. This technique can be very helpful when dealing with more complex scenarios.
 
-In this example our query could look like this : 
+In this example our query could look like this :
 
 ```graphql
-{
+query {
   route(path: "/node/1") {
     ... on Article {
       id
@@ -76,7 +76,7 @@ In this example our query could look like this :
 }
 ```
 
-and the response : 
+and the response :
 
 ```json
 {

doc/starting/README.md

@@ -5,7 +5,7 @@ The module requires installation via `composer`in order to pull in the dependenc
 1. Install the module by running `composer require drupal/graphql:4.x-dev`.
 2. Enable the GraphQL module in extensions.
 3. Login and navigate to `/admin/config/graphql` to create a new server.
-4. At this point you can either start with the test schema provided by the module (see the Introduction section) or start right away making your own custom schema as we will describe in the following sections.
+4. At this point you can either start with the "Example schema" provided by the graphql_examples module (see the Introduction section) or start right away making your own custom schema as we will describe in the following sections.
 
 ## Dependencies
 

doc/starting/custom-schema.md

@@ -1,10 +1,8 @@
 # Creating a custom schema
 
-The best way to start making a new schema is to take the test schema provided by the graphql module in `src/Plugin/GraphQL/Schema/SdlSchemaTest.php` and add it to a custom module of your own. By doing this you can then start adapting the schema to your needs including your own content types and making them available in the schema.
+The best way to start making a new schema is to take the example schema provided by the graphql_examples module in `/graphql/examples/` and copy all the files from the example module to a custom module of your own. By doing this you can then start adapting the schema to your needs including your own content types and making them available in the schema.
 
- The code including all the demo queries and mutations from these docs can be found in [this repository](https://github.com/joaogarin/mydrupalgql).
-
-## Clone the SdlSchemaTest
+## Clone the SdlSchemaTest (deprecated)
 
 First create your own module and call it `mydrupalgql`. Make sure you have a .info file inside the module to make sure drupal will know about this module (for more info see [Custom modules in drupal](https://www.drupal.org/docs/8/creating-custom-modules)).
 Then head to the graphql module folder and copy the content of `src/Plugin/GraphQL/Schema/SdlSchemaTest.php`.