Documentation and docblock improvements

Author: vladar

docs/complementary-tools.md

@@ -3,6 +3,8 @@
 - [Integration with Relay](https://github.com/ivome/graphql-relay-php)
 - [Integration with Laravel 5](https://github.com/Folkloreatelier/laravel-graphql) + [Relay Helpers for Laravel](https://github.com/nuwave/laravel-graphql-relay)
 - [Symfony Bundle](https://github.com/overblog/GraphQLBundle) by Overblog
+- Define types with Doctrine ORM annotations ([for PHP7.1](https://github.com/Ecodev/graphql-doctrine), for [earlier PHP versions](https://github.com/rahuljayaraman/doctrine-graphql))
+- Out of the box integration with any PSR-7 compatible framework (like [Slim](http://slimframework.com) or [Zend Expressive](http://zendframework.github.io/zend-expressive/)) via [Standard Server](executing-queries.md/#using-server)
 
 # Tools
 - [GraphiQL](https://github.com/graphql/graphiql) - An in-browser IDE for exploring GraphQL

docs/concepts.md

@@ -3,7 +3,8 @@ GraphQL is data-centric. On the very top level it is built around three major co
 **Schema**, **Query** and **Mutation**.
 
 You are expected to express your application as **Schema** (aka Type System) and expose it
-with single [HTTP endpoint](http-endpoint/). Application clients (e.g. web or mobile clients) send **Queries** 
+with single HTTP endpoint (e.g. using our [standard server](executing-queries.md#using-server)). 
+Application clients (e.g. web or mobile clients) send **Queries** 
 to this endpoint to request structured data and **Mutations** to perform changes (usually with HTTP POST method).
 
 ## Queries
@@ -34,9 +35,9 @@ It was designed to mirror the structure of expected response:
 }
 ```
 **graphql-php** runtime parses Queries, makes sure that they are valid for given Type System 
-and executes using [data fetching tools](type-system/object-types/#data-fetching) provided by you 
+and executes using [data fetching tools](data-fetching.md) provided by you 
 as a part of integration. Queries are supposed to be idempotent.
- 
+
 ## Mutations
 Mutations use advanced features of the very same query language (like arguments and variables)  
 and have only semantic difference from Queries:
@@ -135,4 +136,4 @@ $blogPostType = new ObjectType([
 # Further Reading
 To get deeper understanding of GraphQL concepts - [read the docs on official GraphQL website](http://graphql.org/learn/)
 
-To get started with **graphql-php** - continue to next section ["Getting Started"](getting-started/)
+To get started with **graphql-php** - continue to next section ["Getting Started"](getting-started.md)

docs/data-fetching.md

@@ -4,7 +4,7 @@ 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 
 runs special **resolve** function on each field. This **resolve** function is provided by you as a part of 
-[field definition](type-system/object-types/#field-configuration-options) or [query execution call](executing-queries/#overview).
+[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)
 or passed down to nested fields (for objects).
@@ -117,11 +117,11 @@ 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**.
 
-To override the default resolver, pass it as an argument of [executeQuery](executing-queries) call.
+To override the default resolver, pass it as an argument of [executeQuery](executing-queries.md) call.
 
 # Default Field Resolver per Type
 Sometimes it might be convenient to set default field resolver per type. You can do so by providing
-[resolveField option in type config](type-system/object-types/#configuration-options). For example:
+[resolveField option in type config](type-system/object-types.md#configuration-options). For example:
 
 ```php
 $userType = new ObjectType([

docs/error-handling.md

@@ -1,7 +1,7 @@
 # Errors in GraphQL
 
 Query execution process never throws exceptions. Instead all errors are caught and collected in 
-[execution result](executing-queries/#execution-result).
+[execution result](executing-queries.md#execution-result).
 
 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)
@@ -144,7 +144,7 @@ $result = GraphQL::executeQuery(/* $args */)
     ->toArray();
 ```
 
-Note that when you pass [debug flags](#debugging-tools) to `$result->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

docs/executing-queries.md

@@ -1,9 +1,9 @@
 # Using Facade Method
 Query execution is a complex process involving multiple steps, including query **parsing**, 
-**validating** and finally **executing** against your [schema](type-system/schema/).
+**validating** and finally **executing** against your [schema](type-system/schema.md).
 
 **graphql-php** provides convenient facade for this process in class 
-[`GraphQL\GraphQL`](/reference/#graphqlgraphql):
+[`GraphQL\GraphQL`](reference.md#graphqlgraphql):
 
 ```php
 use GraphQL\GraphQL;
@@ -20,7 +20,7 @@ $result = GraphQL::executeQuery(
 );
 ```
 
-It returns an instance of [`GraphQL\Executor\ExecutionResult`](/reference/#graphqlexecutorexecutionresult) 
+It returns an instance of [`GraphQL\Executor\ExecutionResult`](reference.md#graphqlexecutorexecutionresult) 
 which can be easily converted to array:
 
 ```php
@@ -30,19 +30,19 @@ $serializableResult = $result->toArray();
 Returned array contains **data** and **errors** keys, as described by 
 [GraphQL spec](http://facebook.github.io/graphql/#sec-Response-Format). 
 This array is suitable for further serialization (e.g. using **json_encode**).
-See also section on [error handling and formatting](error-handling/).
+See also section on [error handling and formatting](error-handling.md).
 
 Description of **executeQuery** method arguments:
 
 Argument     | Type     | Notes
 ------------ | -------- | -----
-schema       | [`GraphQL\Type\Schema`](#) | **Required.** Instance of your application [Schema](type-system/schema/)
+schema       | [`GraphQL\Type\Schema`](#) | **Required.** Instance of your application [Schema](type-system/schema.md)
 queryString  | `string` or `GraphQL\Language\AST\DocumentNode` | **Required.** Actual GraphQL query string to be parsed, validated and executed. If you parse query elsewhere before executing - pass corresponding ast document here to avoid new parsing.
-rootValue  | `mixed` | Any value that represents a root of your data graph. It is passed as 1st argument to field resolvers of [Query type](type-system/schema/#query-and-mutation-types). Can be omitted or set to null if actual root values are fetched by Query type itself.
-context  | `mixed` | Any value that holds information shared between all field resolvers. Most often they use it to pass currently logged in user, locale details, etc.<br><br>It will be available as 3rd argument in all field resolvers. (see section on [Field Definitions](type-system/object-types/#field-configuration-options) for reference) **graphql-php** never modifies this value and passes it *as is* to all underlying resolvers.
+rootValue  | `mixed` | Any value that represents a root of your data graph. It is passed as 1st argument to field resolvers of [Query type](type-system/schema.md#query-and-mutation-types). Can be omitted or set to null if actual root values are fetched by Query type itself.
+context  | `mixed` | Any value that holds information shared between all field resolvers. Most often they use it to pass currently logged in user, locale details, etc.<br><br>It will be available as 3rd argument in all field resolvers. (see section on [Field Definitions](type-system/object-types.md#field-configuration-options) for reference) **graphql-php** never modifies this value and passes it *as is* to all underlying resolvers.
 variableValues | `array` | Map of variable values passed along with query string. See section on [query variables on official GraphQL website](http://graphql.org/learn/queries/#variables)
 operationName | `string` | Allows the caller to specify which operation in queryString will be run, in cases where queryString contains multiple top-level operations.
-fieldResolver | `callable` | A resolver function to use when one is not provided by the schema. If not provided, the [default field resolver is used](data-fetching/#default-field-resolver).
+fieldResolver | `callable` | A resolver function to use when one is not provided by the schema. If not provided, the [default field resolver is used](data-fetching.md#default-field-resolver).
 validationRules | `array` | A set of rules for query validation step. Default value is all available rules. Empty array would allow to skip query validation (may be convenient for persisted queries which are validated before persisting and assumed valid during execution)
 
 # Using Server
@@ -94,17 +94,17 @@ PSR-7 is useful when you want to integrate the server into existing framework:
 
 Argument     | Type     | Notes
 ------------ | -------- | -----
-schema       | [`Schema`](reference/#graphqltypeschema) | **Required.** Instance of your application [Schema](type-system/schema/)
-rootValue  | `mixed` | Any value that represents a root of your data graph. It is passed as 1st argument to field resolvers of [Query type](type-system/schema/#query-and-mutation-types). Can be omitted or set to null if actual root values are fetched by Query type itself.
-context  | `mixed` | Any value that holds information shared between all field resolvers. Most often they use it to pass currently logged in user, locale details, etc.<br><br>It will be available as 3rd argument in all field resolvers. (see section on [Field Definitions](type-system/object-types/#field-configuration-options) for reference) **graphql-php** never modifies this value and passes it *as is* to all underlying resolvers.
-fieldResolver | `callable` | A resolver function to use when one is not provided by the schema. If not provided, the [default field resolver is used](data-fetching/#default-field-resolver).
-validationRules | `array` or `callable` | A set of rules for query validation step. Default value is all available rules. Empty array would allow to skip query validation (may be convenient for persisted queries which are validated before persisting and assumed valid during execution).<br><br>Pass `callable` to return different validation rules for different queries (e.g. empty array for persisted query and full list of rules for regular queries). When passed, it is expected to have following signature: <br><br> **function (OperationParams $params, DocumentNode $node, $operationType): array** <br><br> See also docs on [OperationParams](reference/#graphqlserveroperationparams).
+schema       | [`Schema`](reference.md#graphqltypeschema) | **Required.** Instance of your application [Schema](type-system/schema/)
+rootValue  | `mixed` | Any value that represents a root of your data graph. It is passed as 1st argument to field resolvers of [Query type](type-system/schema.md#query-and-mutation-types). Can be omitted or set to null if actual root values are fetched by Query type itself.
+context  | `mixed` | Any value that holds information shared between all field resolvers. Most often they use it to pass currently logged in user, locale details, etc.<br><br>It will be available as 3rd argument in all field resolvers. (see section on [Field Definitions](type-system/object-types.md#field-configuration-options) for reference) **graphql-php** never modifies this value and passes it *as is* to all underlying resolvers.
+fieldResolver | `callable` | A resolver function to use when one is not provided by the schema. If not provided, the [default field resolver is used](data-fetching.md#default-field-resolver).
+validationRules | `array` or `callable` | A set of rules for query validation step. Default value is all available rules. Empty array would allow to skip query validation (may be convenient for persisted queries which are validated before persisting and assumed valid during execution).<br><br>Pass `callable` to return different validation rules for different queries (e.g. empty array for persisted query and full list of rules for regular queries). When passed, it is expected to have following signature: <br><br> **function (OperationParams $params, DocumentNode $node, $operationType): array** <br><br> See also docs on [OperationParams](reference.md#graphqlserveroperationparams).
 queryBatching | `bool` | Flag indicating whether this server supports query batching ([apollo-style](https://dev-blog.apollodata.com/query-batching-in-apollo-63acfd859862)).<br><br> Defaults to **false**
-debug | `int` | Debug flags. See [docs on error debugging](error-handling/#debugging-tools) (flag values are the same).
-persistentQueryLoader | `callable` | Function which is called to fetch actual query when server encounters **queryId** in request vs **query**.<br><br> Server does not implement persistence part (which you will have to build on your own), but it allows you to execute queries which were persisted previously.<br><br> Expected function signature:<br> **function ($queryId, OperationParams $params)** <br><br>Function is expected to return query **string** or parsed **DocumentNode** <br><br> See also docs on [OperationParams](reference/#graphqlserveroperationparams). <br><br> [Read more about persisted queries](https://dev-blog.apollodata.com/persisted-graphql-queries-with-apollo-client-119fd7e6bba5).
-errorFormatter | `callable` | Custom error formatter. See [error handling docs](error-handling/#custom-error-handling-and-formatting).
-errorsHandler | `callable` | Custom errors handler. See [error handling docs](error-handling/#custom-error-handling-and-formatting).
-promiseAdapter | [`PromiseAdapter`](reference/#graphqlexecutorpromisepromiseadapter) | Required for [Async PHP](data-fetching/#async-php) only. 
+debug | `int` | Debug flags. See [docs on error debugging](error-handling.md#debugging-tools) (flag values are the same).
+persistentQueryLoader | `callable` | Function which is called to fetch actual query when server encounters **queryId** in request vs **query**.<br><br> Server does not implement persistence part (which you will have to build on your own), but it allows you to execute queries which were persisted previously.<br><br> Expected function signature:<br> **function ($queryId, OperationParams $params)** <br><br>Function is expected to return query **string** or parsed **DocumentNode** <br><br> See also docs on [OperationParams](reference.md#graphqlserveroperationparams). <br><br> [Read more about persisted queries](https://dev-blog.apollodata.com/persisted-graphql-queries-with-apollo-client-119fd7e6bba5).
+errorFormatter | `callable` | Custom error formatter. See [error handling docs](error-handling.md#custom-error-handling-and-formatting).
+errorsHandler | `callable` | Custom errors handler. See [error handling docs](error-handling.md#custom-error-handling-and-formatting).
+promiseAdapter | [`PromiseAdapter`](reference.md#graphqlexecutorpromisepromiseadapter) | Required for [Async PHP](data-fetching/#async-php) only. 
 
 **Server config instance**
 
@@ -129,7 +129,7 @@ $server = new StandardServer($config);
 Standard Server supports query batching ([apollo-style](https://dev-blog.apollodata.com/query-batching-in-apollo-63acfd859862)).
 
 One of the major benefits of Server over sequence of **executeQuery()** calls is that 
-[Deferred resolvers](data-fetching/#solving-n1-problem) won't be isolated in queries.
+[Deferred resolvers](data-fetching.md#solving-n1-problem) won't be isolated in queries.
 
 So for example following batch will require single DB request (if user field is deferred):
 

docs/getting-started.md

@@ -60,17 +60,18 @@ $queryType = new ObjectType([
         ],
     ],
 ]);
+
 ```
 
-(Note: type definition can be expressed in [different styles](type-system/#type-definition-styles), 
+(Note: type definition can be expressed in [different styles](type-system/index.md#type-definition-styles), 
 but this example uses **inline** style for simplicity)
 
 The interesting piece here is `resolve` option of field definition. It is responsible for retuning 
-value of our field. Values of **scalar** fields will be directly included in response while values of 
-**complex** fields (objects, interfaces, unions) will be passed down to nested field resolvers 
+a value of our field. Values of **scalar** fields will be directly included in response while values of 
+**composite** fields (objects, interfaces, unions) will be passed down to nested field resolvers 
 (not in this example though).
 
-Now when our type is ready, let's create GraphQL endpoint for it `graphql.php`:
+Now when our type is ready, let's create GraphQL endpoint file for it **graphql.php**:
 
 ```php
 <?php
@@ -89,30 +90,32 @@ $variableValues = isset($input['variables']) ? $input['variables'] : null;
 try {
     $rootValue = ['prefix' => 'You said: '];
     $result = GraphQL::executeQuery($schema, $query, $rootValue, null, $variableValues);
+    $output = $result->toArray();
 } catch (\Exception $e) {
-    $result = [
+    $output = [
         'errors' => [
             [
                 'message' => $e->getMessage()
             ]
         ]
     ];
 }
-header('Content-Type: application/json; charset=UTF-8');
-echo json_encode($result);
+header('Content-Type: application/json');
+echo json_encode($output);
 ```
 
-Our example is ready. Try it by running:
+Our example is finished. Try it by running:
 ```sh
 php -S localhost:8000 graphql.php
-curl http://localhost:8000 -d '{"query": "query { echo(message: \"Hello World\") }" }'
+curl http://localhost:8080 -d '{"query": "query { echo(message: \"Hello World\") }" }'
 ```
 
-Check out the full [source code](https://github.com/webonyx/graphql-php/blob/master/examples/00-hello-world) of this example.
+Check out the full [source code](https://github.com/webonyx/graphql-php/blob/master/examples/00-hello-world) of this example
+which also includes simple mutation.
 
 Obviously hello world only scratches the surface of what is possible. 
 So check out next example, which is closer to real-world apps.
-Or keep reading about [schema definition](type-system/).
+Or keep reading about [schema definition](type-system/index.md).
 
 # Blog example
 It is often easier to start with full-featured example and then get back to documentation

docs/how-it-works.md

@@ -22,10 +22,13 @@ There are 3 types of errors in GraphQL:
 Obviously when **Syntax** or **Validation** error is detected - process is interrupted and query is not 
 executed.
 
+Execution process never throws exceptions. Instead all errors are caught and collected in 
+execution result.
+
 GraphQL is forgiving to **Execution** errors which occur in resolvers of nullable fields. 
 If such field throws or returns unexpected value the value of the field in response will be simply 
 replaced with `null` and error entry will be registered.
 
-If exception is thrown in non-null field - error bubbles up to first nullable field. This nullable field is  
-replaced with `null` and error entry is added to response. If all fields up to the root are non-null - 
-**data** entry will be removed from response and only **errors** key will be presented.
+If exception is thrown in non-null field - error bubbles up to first nullable field. This nullable 
+field is replaced with `null` and error entry is added to response. If all fields up to the root are 
+non-null - **data** entry will be removed from response and only **errors** key will be presented.