Documentation improvements

Author: vladar

UPGRADE.md

@@ -146,6 +146,8 @@ It requires promise adapter in it's first argument and always returns a `Promise
 Old methods `GraphQL::execute` and `GraphQL::executeAndReturnResult` still work in backwards-compatible manner, 
 but they are deprecated and will be removed eventually.
 
+Same applies to Executor: use `Executor::promiseToExecute()` vs `Executor::execute()`.
+
 ## Upgrade v0.7.x > v0.8.x
 All of those changes apply to those who extends various parts of this library.
 If you only use the library and don't try to extend it - everything should work without breaks.

docs/complementary-tools.md

@@ -11,3 +11,4 @@
 - [ChromeiQL](https://chrome.google.com/webstore/detail/chromeiql/fkkiamalmpiidkljmicmjfbieiclmeij)
   or [GraphiQL Feen](https://chrome.google.com/webstore/detail/graphiql-feen/mcbfdonlkfpbfdpimkjilhdneikhfklp) -
   GraphiQL as Google Chrome extension
+- [DataLoader PHP](https://github.com/overblog/dataloader-php) - as a ready implementation for [deferred resolvers](data-fetching.md#solving-n1-problem)

docs/data-fetching.md

@@ -2,11 +2,11 @@
 GraphQL is data-storage agnostic. You can use any underlying data storage engine, including SQL or NoSQL database, 
 plain files or in-memory data structures.
 
-In order to convert GraphQL query to PHP array **graphql-php** traverses query fields (using depth-first algorithm) and 
+In order to convert the GraphQL query to PHP array, **graphql-php** traverses query fields (using depth-first algorithm) and 
 runs special **resolve** function on each field. This **resolve** function is provided by you as a part of 
 [field definition](type-system/object-types.md#field-configuration-options) or [query execution call](executing-queries.md#overview).
 
-Result returned by **resolve** function is directly included in response (for scalars and enums)
+Result returned by **resolve** function is directly included in the response (for scalars and enums)
 or passed down to nested fields (for objects).
 
 Let's walk through an example. Consider following GraphQL query:
@@ -25,6 +25,9 @@ Let's walk through an example. Consider following GraphQL query:
 We need a Schema that can fulfill it. On the very top level the Schema contains Query type:
 
 ```php
+<?php
+use GraphQL\Type\Definition\ObjectType;
+
 $queryType = new ObjectType([
   'name' => 'Query',
   'fields' => [
@@ -46,12 +49,16 @@ $queryType = new ObjectType([
 
 As we see field **lastStory** has **resolve** function that is responsible for fetching data.
 
-In our example we simply return array value, but in real-world application you would query
-your database/cache/search index and return result.
+In our example, we simply return array value, but in the real-world application you would query
+your database/cache/search index and return the result.
 
 Since **lastStory** is of composite type **BlogStory** this result is passed down to fields of this type:
 
 ```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
 $blogStoryType = new ObjectType([
   'name' => 'BlogStory',
   'fields' => [
@@ -83,8 +90,8 @@ $blogStoryType = new ObjectType([
 
 Here **$blogStory** is the array returned by **lastStory** field above. 
 
-Again: in real-world applications you would fetch user data from datastore by **authorId** and return it.
-Also note that you don't have to return arrays. You can return any value, **graphql-php** will pass it untouched
+Again: in the real-world applications you would fetch user data from data store by **authorId** and return it.
+Also, note that you don't have to return arrays. You can return any value, **graphql-php** will pass it untouched
 to nested resolvers.
 
 But then the question appears - field **title** has no **resolve** option. How is it resolved?
@@ -95,7 +102,8 @@ for a field you simply override this default resolver.
 # Default Field Resolver
 **graphql-php** provides following default field resolver:
 ```php
-function defaultFieldResolver($source, $args, $context, ResolveInfo $info)
+<?php
+function defaultFieldResolver($source, $args, $context, \GraphQL\Type\Definition\ResolveInfo $info)
 {
     $fieldName = $info->fieldName;
     $property = null;
@@ -115,7 +123,7 @@ function defaultFieldResolver($source, $args, $context, ResolveInfo $info)
 ```
 
 As you see it returns value by key (for arrays) or property (for objects). 
-If value is not set - it returns **null**.
+If the value is not set - it returns **null**.
 
 To override the default resolver, pass it as an argument of [executeQuery](executing-queries.md) call.
 
@@ -124,6 +132,11 @@ Sometimes it might be convenient to set default field resolver per type. You can
 [resolveField option in type config](type-system/object-types.md#configuration-options). For example:
 
 ```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\ResolveInfo;
+
 $userType = new ObjectType([
   'name' => 'User',
   'fields' => [
@@ -167,13 +180,14 @@ Consider following GraphQL query:
 }
 ```
 
-Naive field resolution process would require up to 10 calls to underlying data store to fetch authors for all 10 stories.
+Naive field resolution process would require up to 10 calls to the underlying data store to fetch authors for all 10 stories.
 
-**graphql-php** provides tools to mitigate this problem: it allows you to defer actual field resolution to later stage 
+**graphql-php** provides tools to mitigate this problem: it allows you to defer actual field resolution to a later stage 
 when one batched query could be executed instead of 10 distinct queries.
 
-Here is an example of `BlogStory` resolver for field `author` that uses deferring:
+Here is an example of **BlogStory** resolver for field **author** that uses deferring:
 ```php
+<?php
 'resolve' => function($blogStory) {
     MyUserBuffer::add($blogStory['authorId']);
 
@@ -184,18 +198,16 @@ Here is an example of `BlogStory` resolver for field `author` that uses deferrin
 }
 ```
 
-In this example we fill up buffer with 10 author ids first. Then **graphql-php** continues 
+In this example, we fill up the buffer with 10 author ids first. Then **graphql-php** continues 
 resolving other non-deferred fields until there are none of them left.
 
-After that it calls `Closures` wrapped by `GraphQL\Deferred` which in turn load all buffered 
-ids once (using SQL IN(?), Redis MGET or other similar tools) and return final field value.
+After that, it calls closures wrapped by `GraphQL\Deferred` which in turn load all buffered 
+ids once (using SQL IN(?), Redis MGET or other similar tools) and returns final field value.
 
 Originally this approach was advocated by Facebook in their [Dataloader](https://github.com/facebook/dataloader)
-project.
-
-This solution enables very interesting optimizations at no cost. Consider following query:
+project. This solution enables very interesting optimizations at no cost. Consider the following query:
 
-```
+```graphql
 {
   topStories(limit: 10) {
     author {
@@ -212,14 +224,14 @@ This solution enables very interesting optimizations at no cost. Consider follow
 }
 ```
 
-Even if `author` field is located on different levels of query - it can be buffered in the same buffer.
-In this example only one query will be executed for all story authors comparing to 20 queries
-in naive implementation.
+Even though **author** field is located on different levels of the query - it can be buffered in the same buffer.
+In this example, only one query will be executed for all story authors comparing to 20 queries
+in a naive implementation.
 
 # Async PHP
-Since: 0.10.0 (version 0.9.0 had slightly different API which is deprecated)
+Since: 0.10.0 (version 0.9.0 had slightly different API which still works, but is deprecated)
 
-If your project runs in environment that supports async operations 
+If your project runs in an environment that supports async operations 
 (like HHVM, ReactPHP, Icicle.io, appserver.io, PHP threads, etc) 
 you can leverage the power of your platform to resolve some fields asynchronously.
 
@@ -230,6 +242,10 @@ To start using this feature, switch facade method for query execution from
 **executeQuery** to **promiseToExecute**:
 
 ```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Executor\ExecutionResult;
+
 $promise = GraphQL::promiseToExecute(
     $promiseAdapter,
     $schema, 
@@ -252,6 +268,6 @@ Where **$promiseAdapter** is an instance of:
   `GraphQL\Executor\Promise\Adapter\ReactPromiseAdapter`
 
 * Other platforms: write your own class implementing interface: <br> 
-  `GraphQL\Executor\Promise\PromiseAdapter`. 
+  [`GraphQL\Executor\Promise\PromiseAdapter`](reference.md#graphqlexecutorpromisepromiseadapter). 
 
 Then your **resolve** functions should return promises of your platform instead of `GraphQL\Deferred`s.

docs/error-handling.md

@@ -1,47 +1,52 @@
 # Errors in GraphQL
 
-Query execution process never throws exceptions. Instead all errors are caught and collected in 
-[execution result](executing-queries.md#execution-result).
+Query execution process never throws exceptions. Instead, all errors are caught and collected. 
+After execution, they are available in **$errors** prop of 
+[`GraphQL\Executor\ExecutionResult`](reference.md#graphqlexecutorexecutionresult).
 
-Later `$result->toArray()` automatically converts these errors to array using default 
-error formatting. But you can apply [custom error filtering and formatting](#custom-error-filtering-and-formatting)
+When the result is converted to a serializable array using its **toArray()** method, all errors are 
+converted to arrays as well using default error formatting (see below). 
+
+Alternatively, you can apply [custom error filtering and formatting](#custom-error-handling-and-formatting)
 for your specific requirements.
 
 # Default Error formatting
-By default each error entry is converted to associative array with following structure:
+By default, each error entry is converted to an associative array with following structure:
 
 ```php
+<?php
 [
     'message' => 'Error message',
     'category' => 'graphql',
     'locations' => [
         ['line' => 1, 'column' => 2]
     ],
-    'path': [
+    'path' => [
         'listField',
         0,
         'fieldWithException'
     ]
-]
+];
 ```
-Entry at key **locations** points to character in query string which caused the error.
-In some cases (like deep fragment fields) locations will include several entries to track down path to 
-field with error in query.
+Entry at key **locations** points to a character in query string which caused the error.
+In some cases (like deep fragment fields) locations will include several entries to track down 
+the path to field with the error in query.
 
-Entry at key **path** exists only for errors caused by exceptions thrown in resolvers. It contains path 
-from the very root field to actual field value producing an error 
+Entry at key **path** exists only for errors caused by exceptions thrown in resolvers. 
+It contains a path from the very root field to actual field value producing an error 
 (including indexes for list types and field names for composite types). 
 
 **Internal errors**
 
-As of version **0.10.0** all exceptions thrown in resolvers are reported with generic message **"Internal server error"**.
+As of version **0.10.0**, all exceptions thrown in resolvers are reported with generic message **"Internal server error"**.
 This is done to avoid information leak in production environments (e.g. database connection errors, file access errors, etc).
 
-Only exceptions implementing interface `GraphQL\Error\ClientAware` and claiming themselves as **safe** will 
-be reported with full error message.
+Only exceptions implementing interface [`GraphQL\Error\ClientAware`](reference.md#graphqlerrorclientaware) and claiming themselves as **safe** will 
+be reported with a full error message.
 
 For example:
 ```php
+<?php
 use GraphQL\Error\ClientAware;
 
 class MySafeException extends \Exception implements ClientAware
@@ -57,20 +62,21 @@ class MySafeException extends \Exception implements ClientAware
     }
 }
 ```
-When such exception is thrown it will be reported with full error message:
+When such exception is thrown it will be reported with a full error message:
 ```php
+<?php
 [
     'message' => 'My reported error',
     'category' => 'businessLogic',
     'locations' => [
         ['line' => 10, 'column' => 2]
     ],
-    'path': [
+    'path' => [
         'path',
         'to',
         'fieldWithException'
     ]
-]
+];
 ```
 
 To change default **"Internal server error"** message to something else, use: 
@@ -91,26 +97,29 @@ $result = GraphQL::executeQuery(/*args*/)->toArray($debug);
 
 This will make each error entry to look like this:
 ```php
+<?php
 [
     'debugMessage' => 'Actual exception message',
     'message' => 'Internal server error',
     'category' => 'internal',
     'locations' => [
         ['line' => 10, 'column' => 2]
     ],
-    'path': [
+    'path' => [
         'listField',
         0,
         'fieldWithException'
     ],
     'trace' => [
         /* Formatted original exception trace */
     ]
-]
+];
 ```
 
 If you prefer first resolver exception to be re-thrown, use following flags:
 ```php
+<?php
+use GraphQL\GraphQL;
 use GraphQL\Error\Debug;
 $debug = Debug::INCLUDE_DEBUG_MESSAGE | Debug::RETHROW_INTERNAL_EXCEPTIONS;
 
@@ -121,12 +130,14 @@ $result = GraphQL::executeQuery(/*args*/)->toArray($debug);
 # Custom Error Handling and Formatting
 It is possible to define custom **formatter** and **handler** for result errors.
 
-**Formatter** is responsible for converting instances of `GraphQL\Error\Error` to array.
-**Handler** is useful for error filtering and logging. 
+**Formatter** is responsible for converting instances of [`GraphQL\Error\Error`](reference.md#graphqlerrorerror) 
+to an array. **Handler** is useful for error filtering and logging. 
 
-For example these are default formatter and handler:
+For example, these are default formatter and handler:
 
 ```php
+<?php
+use GraphQL\GraphQL;
 use GraphQL\Error\Error;
 use GraphQL\Error\FormattedError;
 
@@ -144,7 +155,7 @@ $result = GraphQL::executeQuery(/* $args */)
     ->toArray();
 ```
 
-Note that when you pass [debug flags](#debugging-tools) to `toArray()` your custom formatter will still be 
+Note that when you pass [debug flags](#debugging-tools) to **toArray()** your custom formatter will still be 
 decorated with same debugging information mentioned above.
 
 # Schema Errors
@@ -155,6 +166,11 @@ Usually such errors mean that there is some logical error in your schema and it
 when it makes sense to return `500` error code for GraphQL endpoint:
 
 ```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Type\Schema;
+use GraphQL\Error\FormattedError;
+
 try {
     $schema = new Schema([
         // ...
@@ -163,9 +179,9 @@ try {
     $body = GraphQL::executeQuery($schema, $query);
     $status = 200;
 } catch(\Exception $e) {
-    $body = json_encode([
-        'message' => 'Unexpected error'
-    ]);
+    $body = [
+        'errors' => [FormattedError::createFromException($e)]
+    ];
     $status = 500;
 }