Documentation and docblock improvements

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.
+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/#field-configuration-options) for reference) **graphql-php** never modifies this value and passes it *as is* to all underlying resolvers.
+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/)
+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/#query-and-mutation-types). Can be omitted or set to null if actual root values are fetched by Query type itself.
+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/#field-configuration-options) for reference) **graphql-php** never modifies this value and passes it *as is* to all underlying resolvers.
+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/#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` 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).
+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).
+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/#graphqlserveroperationparams). <br><br> [Read more about persisted queries](https://dev-blog.apollodata.com/persisted-graphql-queries-with-apollo-client-119fd7e6bba5).
+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/#custom-error-handling-and-formatting).
+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/#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/#graphqlexecutorpromisepromiseadapter) | Required for [Async PHP](data-fetching/#async-php) only. 
+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 
+a 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 
+**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,8 +90,9 @@ $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()
@@ -98,21 +100,22 @@ try {
         ]
     ];
 }
-header('Content-Type: application/json; charset=UTF-8');
+header('Content-Type: application/json');
-echo json_encode($result);
+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  
+If exception is thrown in non-null field - error bubbles up to first nullable field. This nullable 
-replaced with `null` and error entry is added to response. If all fields up to the root are non-null - 
+field is replaced with `null` and error entry is added to response. If all fields up to the root are 
-**data** entry will be removed from response and only **errors** key will be presented.
+non-null - **data** entry will be removed from response and only **errors** key will be presented.

docs/index.md

@@ -19,29 +19,32 @@ All of them equally apply to this PHP implementation.
 
 # About graphql-php
 
-**graphql-php** is a feature-complete implementation of GraphQL specification in PHP (5.4+, 7.0+). 
+**graphql-php** is a feature-complete implementation of GraphQL specification in PHP (5.5+, 7.0+). 
 It was originally inspired by [reference JavaScript implementation](https://github.com/graphql/graphql-js) 
 published by Facebook.
 
 This library is a thin wrapper around your existing data layer and business logic. 
 It doesn't dictate how these layers are implemented or which storage engines 
-are used. Instead it provides tools for creating rich API for your existing app. 
+are used. Instead it provides tools for creating rich API for your existing app.
+ 
+Library features include:
 
-These tools include:
+ - Primitives to express your app as a [Type System](type-system/index.md)
+ - Validation and introspection of this Type System (for compatibility with tools like [GraphiQL](complementary-tools.md#tools))
+ - Parsing, validating and [executing GraphQL queries](executing-queries.md) against this Type System
+ - Rich [error reporting](error-handling.md), including query validation and execution errors
+ - Optional tools for [parsing GraphQL Type language](type-system/type-language.md)
+ - Tools for [batching requests](data-fetching.md/#solving-n1-problem) to backend storage
+ - [Async PHP platforms support](data-fetching.md/#async-php) via promises
+ - [Standard HTTP server](executing-queries.md/#using-server)
 
- - Primitives to express your app as a Type System
+Also several [complementary tools](complementary-tools.md) are available which provide integrations with 
- - Tools for validation and introspection of this Type System (for compatibility with tools like [GraphiQL](complementary-tools/#tools))
- - Tools for parsing, validating and executing GraphQL queries against this Type System
- - Rich error reporting, including query validation and execution errors
- - Optional tools for parsing GraphQL Schema Definition language
-
-Also several [complementary tools](complementary-tools/) are available which provide integrations with 
 existing PHP frameworks, add support for Relay, etc.
 
 ## Current Status
 First version of this library (v0.1) was released on August 10th 2015.
 
-Current version (v0.9) supports all features described by GraphQL specification 
+Current version (v0.10) supports all features described by GraphQL specification 
 (including April 2016 add-ons) as well as some experimental features like 
 Schema Language parser.
 
@@ -49,6 +52,3 @@ Ready for real-world usage.
 
 ## Github
 Project source code is [hosted on GitHub](https://github.com/webonyx/graphql-php).
-
-## Framework Integrations
-Read the section about [Complementary tools](complementary-tools/).

docs/reference.md

@@ -1,6 +1,6 @@
 # GraphQL\GraphQL
 This is the primary facade for fulfilling GraphQL operations.
-See [related documentation](executing-queries/).
+See [related documentation](executing-queries.md).
 
 **Class Methods:** 
 ```php
@@ -251,7 +251,7 @@ static function getNamedType($type)
 # GraphQL\Type\SchemaConfig
 Schema configuration class.
 Could be passed directly to schema constructor. List of options accepted by **create** method is
-[described in docs](type-system/schema/#configuration-options).
+[described in docs](type-system/schema.md#configuration-options).
 
 Usage example:
 
@@ -376,7 +376,7 @@ function getDirectives()
 function getTypeLoader()
 ```
 # GraphQL\Type\Schema
-Schema Definition (see [related docs](type-system/schema/))
+Schema Definition (see [related docs](type-system/schema.md))
 
 A Schema is created by supplying the root types of each type of operation:
 query, mutation (optional) and subscription (optional). A schema definition is
@@ -531,7 +531,7 @@ function getDirective($name)
 function assertValid()
 ```
 # GraphQL\Language\Parser
-Parses string containing GraphQL query or [type definition](type-system/type-language/) to Abstract Syntax Tree.
+Parses string containing GraphQL query or [type definition](type-system/type-language.md) to Abstract Syntax Tree.
 
 **Class Methods:** 
 ```php
@@ -649,7 +649,7 @@ visit function.
     ]);
 
 Alternatively to providing enter() and leave() functions, a visitor can
-instead provide functions named the same as the [kinds of AST nodes](reference/#graphqllanguageastnodekind),
+instead provide functions named the same as the [kinds of AST nodes](reference.md#graphqllanguageastnodekind),
 or enter/leave visitors at a named key, leading to four permutations of
 visitor API:
 
@@ -854,7 +854,7 @@ static function promiseToExecute(
 )
 ```
 # GraphQL\Executor\ExecutionResult
-Returned after [query execution](executing-queries/).
+Returned after [query execution](executing-queries.md).
 Represents both - result of successful execution and of a failed one
 (with errors collected in `errors` prop)
 
@@ -950,7 +950,7 @@ function setErrorsHandler(callable $handler)
 function toArray($debug = false)
 ```
 # GraphQL\Executor\Promise\PromiseAdapter
-Provides a means for integration of async PHP platforms ([related docs](data-fetching/#async-php))
+Provides a means for integration of async PHP platforms ([related docs](data-fetching.md#async-php))
 
 **Interface Methods:** 
 ```php
@@ -1044,7 +1044,7 @@ function all(array $promisesOrValues)
 ```
 # GraphQL\Type\Definition\ResolveInfo
 Structure containing information useful for field resolution process.
-Passed as 3rd argument to every field resolver. See [docs on field resolving (data fetching)](data-fetching/).
+Passed as 3rd argument to every field resolver. See [docs on field resolving (data fetching)](data-fetching.md).
 
 **Class Props:** 
 ```php
@@ -1178,9 +1178,9 @@ A list of specific validation rules may be provided. If not provided, the
 default list of rules defined by the GraphQL specification will be used.
 
 Each validation rule is an instance of GraphQL\Validator\Rules\AbstractValidationRule
-which returns a visitor (see the [GraphQL\Language\Visitor API](reference/#graphqllanguagevisitor)).
+which returns a visitor (see the [GraphQL\Language\Visitor API](reference.md#graphqllanguagevisitor)).
 
-Visitor methods are expected to return an instance of [GraphQL\Error\Error](reference/#graphqlerrorerror),
+Visitor methods are expected to return an instance of [GraphQL\Error\Error](reference.md#graphqlerrorerror),
 or array of such instances when invalid.
 
 Optionally a custom TypeInfo instance may be provided. If not provided, one
@@ -1248,7 +1248,7 @@ GraphQL document and/or execution result that correspond to the Error.
 When the error was caused by an exception thrown in resolver, original exception
 is available via `getPrevious()`.
 
-Also read related docs on [error handling](error-handling/)
+Also read related docs on [error handling](error-handling.md)
 
 Class extends standard PHP `\Exception`, so all standard methods of base `\Exception` class
 are available in addition to those listed below.
@@ -1347,7 +1347,7 @@ static function suppress($suppress = false)
 static function enable($enable = false)
 ```
 # GraphQL\Error\ClientAware
-This interface is used for [default error formatting](error-handling/).
+This interface is used for [default error formatting](error-handling.md).
 
 Only errors implementing this interface (and returning true from `isClientSafe()`)
 will be formatted with original error message.
@@ -1377,7 +1377,7 @@ function isClientSafe()
 function getCategory()
 ```
 # GraphQL\Error\Debug
-Collection of flags for [error debugging](error-handling/#debugging-tools).
+Collection of flags for [error debugging](error-handling.md#debugging-tools).
 
 **Class Constants:** 
 ```php
@@ -1387,7 +1387,7 @@ const RETHROW_INTERNAL_EXCEPTIONS = 4;
 ```
 
 # GraphQL\Error\FormattedError
-This class is used for [default error formatting](error-handling/).
+This class is used for [default error formatting](error-handling.md).
 It converts PHP exceptions to [spec-compliant errors](https://facebook.github.io/graphql/#sec-Errors)
 and provides tools for error debugging.
 
@@ -1443,7 +1443,7 @@ Usage Example:
     ]);
     $server->handleRequest();
 
-Or using [ServerConfig](reference/#graphqlserverserverconfig) instance:
+Or using [ServerConfig](reference.md#graphqlserverserverconfig) instance:
 
     $config = GraphQL\Server\ServerConfig::create()
         ->setSchema($mySchema)
@@ -1452,9 +1452,23 @@ Or using [ServerConfig](reference/#graphqlserverserverconfig) instance:
     $server = new GraphQL\Server\StandardServer($config);
     $server->handleRequest();
 
-See [dedicated section in docs](executing-queries/#using-server) for details.
+See [dedicated section in docs](executing-queries.md#using-server) for details.
 
 **Class Methods:** 
+```php
+/**
+ * Converts and exception to error and sends spec-compliant HTTP 500 error.
+ * Useful when an exception is thrown somewhere outside of server execution context
+ * (e.g. during schema instantiation).
+ *
+ * @api
+ * @param \Throwable $error
+ * @param bool $debug
+ * @param bool $exitWhenDone
+ */
+static function send500Error($error, $debug = false, $exitWhenDone = false)
+```
+
 ```php
 /**
  * Creates new instance of a standard GraphQL HTTP server
@@ -1547,7 +1561,7 @@ function getHelper()
 # GraphQL\Server\ServerConfig
 Server configuration class.
 Could be passed directly to server constructor. List of options accepted by **create** method is
-[described in docs](executing-queries/#server-configuration-options).
+[described in docs](executing-queries.md#server-configuration-options).
 
 Usage example:
 

docs/security.md

@@ -21,7 +21,7 @@ DocumentValidator::addRule($rule);
 
 GraphQL::executeQuery(/*...*/);
 ```
-This will set the rule globally. Alternatively you can provide validation rules [per execution](executing-queries/#custom-validation-rules).
+This will set the rule globally. Alternatively you can provide validation rules [per execution](executing-queries.md#custom-validation-rules).
 
 To customize field score add **complexity** function to field definition:
 ```php
@@ -67,14 +67,19 @@ DocumentValidator::addRule($rule);
 GraphQL::executeQuery(/*...*/);
 ```
 
-This will set the rule globally. Alternatively you can provide validation rules [per execution](executing-queries/#custom-validation-rules).
+This will set the rule globally. Alternatively you can provide validation rules [per execution](executing-queries.md#custom-validation-rules).
 
 # Disabling Introspection
+[Introspection](http://graphql.org/learn/introspection/) is a mechanism for fetching schema structure.
+It is used by tools like GraphiQL for autocompletion, query validation, etc.
 
-This is a PHP port of [graphql-disable-introspection](https://github.com/helfer/graphql-disable-introspection).
+Introspection is enabled by default. It means that anybody can get full description of your schema by 
-It is a separate validation rule which prohibits queries that contain **__type** or **__schema** fields. 
+sending special query containing meta fields **__type** and **__schema** .
 
-Introspection is enabled by default. To disable it, add following validation rule:
+If you are not planning to expose your API to general public, it makes sense to disable this feature.
+
+GraphQL PHP provides you separate validation rule which prohibits queries that contain 
+**__type** or **__schema** fields. To disable introspection, add following rule:
 
 ```php
 <?php
@@ -86,4 +91,4 @@ DocumentValidator::addRule(new DisableIntrospection());
 
 GraphQL::executeQuery(/*...*/);
 ```
-This will set the rule globally. Alternatively you can provide validation rules [per execution](executing-queries/#custom-validation-rules).
+This will set the rule globally. Alternatively you can provide validation rules [per execution](executing-queries.md#custom-validation-rules).

docs/type-system/enum-types.md

@@ -3,7 +3,7 @@ Enumeration types are a special kind of scalar that is restricted to a particula
 of allowed values. 
 
 In **graphql-php** enum type is an instance of `GraphQL\Type\Definition\EnumType` 
-(or one of it subclasses) which accepts configuration array in constructor:
+which accepts configuration array in constructor:
 
 ```php
 use GraphQL\Type\Definition\EnumType;
@@ -29,14 +29,14 @@ $episodeEnum = new EnumType([
 ```
 
 This example uses **inline** style for Enum Type definition, but you can also use
-[inheritance](/type-system/#type-definition-styles).
+[inheritance or type language](index.md#type-definition-styles).
 
 # Configuration options
 Enum Type constructor accepts array with following options:
 
 Option | Type | Notes
 ------ | ---- | -----
-name | `string` | **Required.** Name of the type. When not set - inferred from array key (read about [shorthand field definition](#) below)
+name | `string` | **Required.** Name of the type. When not set - inferred from array key (read about [shorthand field definition](#shorthand-definitions) below)
 description | `string` | Plain-text description of the type for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
 values | `array` | List of enumerated items, see below for expected structure of each entry
 
@@ -44,7 +44,7 @@ Each entry of **values** array in turn accepts following options:
 
 Option | Type | Notes
 ------ | ---- | -----
-name | `string` | **Required.** Name of the item. When not set - inferred from array key (read about [shorthand field definition](#) below)
+name | `string` | **Required.** Name of the item. When not set - inferred from array key (read about [shorthand field definition](#shorthand-definitions) below)
 value | `mixed` | Internal representation of enum item in your application (could be any value, including complex objects or callbacks)
 description | `string` | Plain-text description of enum value for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
 deprecationReason | `string` | Text describing why this enum value is deprecated. When not empty - item will not be returned by introspection queries (unless forced)

docs/type-system/index.md

@@ -1,11 +1,11 @@
 # Type System
-To start using GraphQL you are expected to implement a type hierarchy and expose it as [Schema](type-system/schema/). 
+To start using GraphQL you are expected to implement a type hierarchy and expose it as [Schema](schema.md). 
 
 In **graphql-php** `type` is an instance of internal class from 
 `GraphQL\Type\Definition` namespace: `ScalarType`, `ObjectType`, `InterfaceType`, 
 `UnionType`, `InputObjectType` (or one of it's subclasses).
 
-But most of the types in your schema will be [object types](/type-system/object-types/).
+But most of the types in your schema will be [object types](object-types.md).
 
 # Type Definition Styles
 Several styles of type definitions are supported depending on your preferences.
@@ -50,7 +50,7 @@ class MyType extends ObjectType
 }
 ```
 
-Using [GraphQL Type language](graphql.org/learn/schema/#type-language):
+Using [GraphQL Type language](http://graphql.org/learn/schema/#type-language):
 
 ```graphql
 schema {
@@ -68,7 +68,7 @@ input HelloInput {
 }
 ```
 
-[Read more](/type-system/type-language/) about it in a dedicated docs section.
+[Read more](type-language.md) about it in a dedicated docs section.
 
 # Type Registry
 Every type must be presented in Schema by single instance (**graphql-php** 

docs/type-system/input-types.md

@@ -1,5 +1,5 @@
 # About Input and Output Types
-GraphQL receives data from clients via [Field Arguments](object-types/#field-arguments).
+GraphQL receives data from clients via [Field Arguments](object-types.md#field-arguments).
 
 Both - fields and arguments require **type** option in definition. But expected value of this option
 is different for fields and arguments, as in GraphQL argument is conceptually input while field is conceptually 
@@ -7,16 +7,16 @@ output.
 
 Consequentially all types in GraphQL are of two categories: **input** and **output**.
 
-* **Output** types (or field types) are: [Scalar](scalar-types/), [Enum](enum-types/), [Object](object-types/), 
+* **Output** types (or field types) are: [Scalar](scalar-types.md), [Enum](enum-types.md), [Object](object-types.md), 
-[Interface](interfaces/), [Union](unions/)
+[Interface](interfaces.md), [Union](unions.md)
 
-* **Input** types (or argument types) are: [Scalar](scalar-types/), [Enum](enum-types/), InputObject
+* **Input** types (or argument types) are: [Scalar](scalar-types.md), [Enum](enum-types.md), InputObject
 
-Obviously [NonNull and List](lists-and-nonnulls/) types belong to both categories depending on their 
+Obviously [NonNull and List](lists-and-nonnulls.md) types belong to both categories depending on their 
 inner type.
 
-Until now all examples of field **arguments** in this documentation were of [Scalar](scalar-types/) or 
+Until now all examples of field **arguments** in this documentation were of [Scalar](scalar-types.md) or 
-[Enum](enum-types/) types. But you can also easily pass complex objects. 
+[Enum](enum-types.md) types. But you can also easily pass complex objects. 
 
 This is particularly valuable in the case of mutations, where input data might be rather complex.
 
@@ -63,7 +63,7 @@ Every field is an array with following entries:
 Option | Type | Notes
 ------ | ---- | -----
 name | `string` | **Required.** Name of the input field. When not set - inferred from **fields** array key
-type | `Type` | **Required.** Instance of one of [Input Types](input-types/) (`Scalar`, `Enum`, `InputObjectType` + any combination of those with `NonNull` and `List` modifiers)
+type | `Type` | **Required.** Instance of one of [Input Types](input-types.md) (`Scalar`, `Enum`, `InputObjectType` + any combination of those with `NonNull` and `List` modifiers)
 description | `string` | Plain-text description of this input field for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
 defaultValue | `scalar` | Default value of this input field
 

docs/type-system/interfaces.md

@@ -32,7 +32,7 @@ $character = new InterfaceType([
 ]);
 ```
 This example uses **inline** style for Interface definition, but you can also use  
-[inheritance](/type-system/#type-definition-styles).
+[inheritance](index.md#type-definition-styles).
 
 # Configuration options
 Constructor of InterfaceType accepts an array. Below is a full list of allowed options:
@@ -40,7 +40,7 @@ Constructor of InterfaceType accepts an array. Below is a full list of allowed o
 Option | Type | Notes
 ------ | ---- | -----
 name | `string` | **Required.** Unique name of this interface type within Schema
-fields | `array` | **Required.** List of fields required to be defined by interface implementors. Same as [Fields for Object Type](#)
+fields | `array` | **Required.** List of fields required to be defined by interface implementors. Same as [Fields for Object Type](object-types.md#field-configuration-options)
 description | `string` | Plain-text description of this type for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
 resolveType | `callback` returning instance of `ObjectType` | **function($value, $context, GraphQL\Type\Definition\ResolveInfo $info)** Any `callable` that receives `$value` from resolver of the parent field and returns concrete interface implementor for that `$value`.
 
@@ -113,7 +113,7 @@ be resolved:
 **resolve** option to field definition in Interface itself.
 
 2. If field resolution varies from implementor to implementor - you can specify **resolveField** 
-option in [Object Type config](/type-system/object-types/#configuration-options) and handle field 
+option in [Object Type config](object-types.md#configuration-options) and handle field 
 resolutions there 
 (Note: **resolve** option in field definition has precedence over **resolveField** option in object type definition)
 

docs/type-system/lists-and-nonnulls.md

@@ -58,4 +58,4 @@ If resolver of non-null field returns `null`, **graphql-php** will add an error
 result and exclude whole object from output (error will bubble to first nullable parent 
 field which will be set to `null`).
 
-Read section on [Data Fetching](#) for details.
+Read section on [Data Fetching](../data-fetching.md) for details.

docs/type-system/object-types.md

@@ -57,7 +57,7 @@ $blogStory = new ObjectType([
 ]);
 ```
 This example uses **inline** style for Object Type definitions, but you can also use  
-[inheritance](/type-system/#type-definition-styles).
+[inheritance or type language](index.md#type-definition-styles).
 
 
 # Configuration options
@@ -66,21 +66,22 @@ Object type constructor expects configuration array. Below is a full list of ava
 Option       | Type     | Notes
 ------------ | -------- | -----
 name         | `string` | **Required.** Unique name of this object type within Schema
-fields       | `array` or `callback` returning `array` | **Required**. Array describing object fields. See [Fields](#field-definitions) section below for expected structure of each array entry. See also section on [Circular types](#) for explanation of when to use callback for this option.
+fields       | `array` or `callable` returning `array` | **Required**. Array describing object fields. See [Fields](#field-definitions) section below for expected structure of each array entry. See also section on [Circular types](#recurring-and-circular-types) for explanation of when to use callable for this option.
 description  | `string` | Plain-text description of this type for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
-interfaces   | `array` or `callback` returning `array` | List of interfaces implemented by this type. See [Interface Types](/type-system/interface-types) for details. See also section on [Circular types](#) for explanation of when to use callback for this option.
+interfaces   | `array` or `callable` returning `array` | List of interfaces implemented by this type. See [Interface Types](interfaces.md) for details. See also section on [Circular types](#recurring-and-circular-types) for explanation of when to use callable for this option.
-isTypeOf     | `callback` returning `boolean` | **function($value, $context, GraphQL\Type\Definition\ResolveInfo $info)** Expected to return `true` if `$value` qualifies for this type (see section about [Abstract Type Resolution](#) for explanation).
+isTypeOf     | `callable` returning `boolean` | **function($value, $context, GraphQL\Type\Definition\ResolveInfo $info)** Expected to return `true` if `$value` qualifies for this type (see section about [Abstract Type Resolution](interfaces.md#interface-role-in-data-fetching) for explanation).
-resolveField | `callback` returning `mixed` | **function($value, $args, $context, GraphQL\Type\Definition\ResolveInfo $info)** Given the `$value` of this type it is expected to return value for field defined in `$info->fieldName`. Good place to define type-specific strategy for field resolution. See section on [Data Fetching](#) for details.
+resolveField | `callable` returning `mixed` | **function($value, $args, $context, GraphQL\Type\Definition\ResolveInfo $info)** Given the `$value` of this type it is expected to return value for field defined in `$info->fieldName`. Good place to define type-specific strategy for field resolution. See section on [Data Fetching](../data-fetching.md) for details.
 
 # Field configuration options
 Below is a full list of available field configuration options:
 
 Option | Type | Notes
 ------ | ---- | -----
-name | `string` | **Required.** Name of the field. When not set - inferred from **fields** array key (read about [shorthand field definition](#) below)
+name | `string` | **Required.** Name of the field. When not set - inferred from **fields** array key (read about [shorthand field definition](#shorthand-field-definitions) below)
-type | `Type` | **Required.** Instance of internal or custom type. Note: type must be represented by single instance within schema (see also [Type Registry](#))
+type | `Type` | **Required.** Instance of internal or custom type. Note: type must be represented by single instance within schema (see also [Type Registry](index.md#type-registry))
 args | `array` | Array of possible type arguments. Each entry is expected to be an array with keys: **name**, **type**, **description**, **defaultValue**. See [Field Arguments](#field-arguments) section below.
-resolve | `callback` | **function($value, $args, $context, GraphQL\Type\Definition\ResolveInfo $info)** Given the `$value` of this type it is expected to return value for current field. See section on [Data Fetching](#) for details
+resolve | `callable` | **function($value, $args, $context, GraphQL\Type\Definition\ResolveInfo $info)** Given the `$value` of this type it is expected to return value for current field. See section on [Data Fetching](../data-fetching.md) for details
+complexity | `callable` | **function($childrenComplexity, $args)** Used to restrict query complexity. Feature is disabled by default, read section about [Security](../security.md#query-complexity-analysis) to use it.
 description | `string` | Plain-text description of this field for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
 deprecationReason | `string` | Text describing why this field is deprecated. When not empty - field will not be returned by introspection queries (unless forced)
 
@@ -91,7 +92,7 @@ Each argument is an array with following options:
 Option | Type | Notes
 ------ | ---- | -----
 name | `string` | **Required.** Name of the argument. When not set - inferred from **args** array key
-type | `Type` | **Required.** Instance of one of [Input Types](input-types/) (`scalar`, `enum`, `InputObjectType` + any combination of those with `nonNull` and `listOf` modifiers)
+type | `Type` | **Required.** Instance of one of [Input Types](input-types.md) (`scalar`, `enum`, `InputObjectType` + any combination of those with `nonNull` and `listOf` modifiers)
 description | `string` | Plain-text description of this argument for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
 defaultValue | `scalar` | Default value for this argument
 
@@ -145,7 +146,7 @@ $userType = new ObjectType([
 ]);
 ```
 
-Same example for [inheritance style of type definitions](#) using [TypeRegistry](#):
+Same example for [inheritance style of type definitions](index.md#type-definition-styles) using [TypeRegistry](index.md#type-registry):
 ```php
 <?php
 namespace MyApp;
@@ -192,10 +193,10 @@ class MyTypes
 
 # Field Resolution
 Field resolution is the primary mechanism in **graphql-php** for returning actual data for your fields.
-It is implemented using `resolveField` callback in type definition or `resolve`
+It is implemented using `resolveField` callable in type definition or `resolve`
-callback in field definition (which has precedence).
+callable in field definition (which has precedence).
 
-Read section on [Data Fetching]() for complete description of this process.
+Read section on [Data Fetching](../data-fetching.md) for complete description of this process.
 
 # Custom Metadata
 All types in **graphql-php** accept configuration array. In some cases you may be interested in 

docs/type-system/scalar-types.md

@@ -13,7 +13,7 @@ Type::boolean(); // Boolean type
 Type::id();      // ID type
 ```
 Those methods return instances of `GraphQL\Type\Definition\ScalarType` (actually one of it subclasses).
-Use them directly in type definitions, or wrap in your [TypeRegistry](/type-system/#type-registry) 
+Use them directly in type definitions, or wrap in your [TypeRegistry](index.md#type-registry) 
 (if you use one).
 
 # Writing Custom Scalar Types

docs/type-system/schema.md

@@ -2,7 +2,7 @@
 Schema is a container of your type hierarchy, which accepts root types in constructor and provides
 methods for receiving information about your types to internal GrahpQL tools.
 
-In **graphql-php** schema is an instance of [`GraphQL\Type\Schema`](/reference/#graphqltypeschema) 
+In **graphql-php** schema is an instance of [`GraphQL\Type\Schema`](../reference.md#graphqltypeschema) 
 which accepts configuration array in constructor:
 
 ```php
@@ -21,7 +21,7 @@ Schema consists of two root types:
 * `Query` type is a surface of your read API
 * `Mutation` type (optional) exposes write API by declaring all possible mutations in your app. 
 
-Query and Mutation types are regular [object types](object-types/) containing root-level fields 
+Query and Mutation types are regular [object types](object-types.md) containing root-level fields 
 of your API:
 
 ```php
@@ -70,15 +70,15 @@ $mutationType = new ObjectType([
 ```
 
 Keep in mind that other than the special meaning of declaring surface area of your API, 
-those types are the same as any other [object type](object-types/), and their fields work 
+those types are the same as any other [object type](object-types.md), and their fields work 
 exactly the same way.
 
 **Mutation** type is also just a regular object type. The difference is in semantics. 
 Field names of Mutation type are usually verbs and they almost always have arguments - quite often 
-with complex input values (see [Input Types](input-types/) for details).
+with complex input values (see [Input Types](input-types.md) for details).
 
 # Configuration Options
-Schema constructor expects an instance of [`GraphQL\Type\SchemaConfig`](/reference/#graphqltypeschemaconfig) 
+Schema constructor expects an instance of [`GraphQL\Type\SchemaConfig`](../reference.md#graphqltypeschemaconfig) 
 or an array with following options:
 
 Option       | Type     | Notes
@@ -86,7 +86,7 @@ Option       | Type     | Notes
 query        | `ObjectType` | **Required.** Object type (usually named "Query") containing root-level fields of your read API
 mutation     | `ObjectType` | Object type (usually named "Mutation") containing root-level fields of your write API
 subscription     | `ObjectType` | Reserved for future subscriptions implementation. Currently presented for compatibility with introspection query of **graphql-js**, used by various clients (like Relay or GraphiQL)
-directives  | `Directive[]` | Full list of [directives](directives/) supported by your schema. By default contains built-in `@skip` and `@include` directives.<br><br> If you pass your own directives and still want to use built-in directives - add them explicitly. For example: `array_merge(GraphQL::getInternalDirectives(), [$myCustomDirective]`
+directives  | `Directive[]` | Full list of [directives](directives.md) supported by your schema. By default contains built-in `@skip` and `@include` directives.<br><br> If you pass your own directives and still want to use built-in directives - add them explicitly. For example: `array_merge(GraphQL::getStandardDirectives(), [$myCustomDirective]`
 types     | `ObjectType[]` | List of object types which cannot be detected by **graphql-php** during static schema analysis.<br><br>Most often it happens when object type is never referenced in fields directly, but is still a part of schema because it implements an interface which resolves to this object type in it's `resolveType` callback. <br><br> Note that you are not required to pass all of your types here - it is simply a workaround for concrete use-case.
 
 # Lazy loading of types

docs/type-system/type-language.md

@@ -34,7 +34,7 @@ $schema = BuildSchema::build($contents);
 By default such schema is created without any resolvers. As a result it doesn't support **Interfaces** and **Unions**
 because it is impossible to resolve actual implementations during execution.
 
-Also we have to rely on [default field resolver](/data-fetching/#default-field-resolver) and **root value** in 
+Also we have to rely on [default field resolver](../data-fetching.md#default-field-resolver) and **root value** in 
 order to execute query against this schema.
 
 # Defining resolvers
@@ -42,8 +42,8 @@ In order to enable **Interfaces**, **Unions** and custom field resolvers you can
 **type config decorator** to schema builder. 
 
 It accepts default type config produced by builder and is expected to add missing options like 
-[`resolveType`](/type-system/interfaces/#configuration-options) for interface types or 
+[`resolveType`](interfaces.md#configuration-options) for interface types or 
-[`resolveField`](/type-system/object-types/#configuration-options) for object types.
+[`resolveField`](object-types.md#configuration-options) for object types.
 
 ```php
 <?php
@@ -60,7 +60,7 @@ $schema = BuildSchema::build($contents, $typeConfigDecorator);
 ```
 
 # Performance considerations
-Method `BuildSchema::build()` produces a [lazy schema](/type-system/schema/#lazy-loading-of-types)
+Method `BuildSchema::build()` produces a [lazy schema](schema.md#lazy-loading-of-types)
 automatically, so it works efficiently even with very large schemas.
 
 But parsing type definition file on each request is suboptimal, so it is recommended to cache 

docs/type-system/unions.md

@@ -23,7 +23,7 @@ $searchResultType = new UnionType([
 ```
 
 This example uses **inline** style for Union definition, but you can also use  
-[inheritance](/type-system/#type-definition-styles).
+[inheritance or type language](index.md#type-definition-styles).
 
 # Configuration options
 Constructor of UnionType accepts an array. Below is a full list of allowed options:

mkdocs.yml

@@ -2,6 +2,7 @@ site_name: graphql-php
 pages:
 - About: index.md
 - Getting Started: getting-started.md
+- Complementary Tools: complementary-tools.md
 - Type Definitions:
   - Introduction: type-system/index.md
   - Object Types: type-system/object-types.md
@@ -22,5 +23,4 @@ pages:
 # - Performance tips: performance.md
 - How it works: how-it-works.md
 - Class Reference: reference.md
-- Complementary Tools: complementary-tools.md
 theme: readthedocs

src/Error/ClientAware.php

@@ -2,7 +2,7 @@
 namespace GraphQL\Error;
 
 /**
- * This interface is used for [default error formatting](error-handling/).
+ * This interface is used for [default error formatting](error-handling.md).
  *
  * Only errors implementing this interface (and returning true from `isClientSafe()`)
  * will be formatted with original error message.

src/Error/Debug.php

@@ -2,7 +2,7 @@
 namespace GraphQL\Error;
 
 /**
- * Collection of flags for [error debugging](error-handling/#debugging-tools).
+ * Collection of flags for [error debugging](error-handling.md#debugging-tools).
  */
 class Debug
 {

src/Error/Error.php

@@ -14,7 +14,7 @@ use GraphQL\Utils\Utils;
  * When the error was caused by an exception thrown in resolver, original exception
  * is available via `getPrevious()`.
  *
- * Also read related docs on [error handling](error-handling/)
+ * Also read related docs on [error handling](error-handling.md)
  *
  * Class extends standard PHP `\Exception`, so all standard methods of base `\Exception` class
  * are available in addition to those listed below.

src/Error/FormattedError.php

@@ -7,7 +7,7 @@ use GraphQL\Type\Definition\WrappingType;
 use GraphQL\Utils\Utils;
 
 /**
- * This class is used for [default error formatting](error-handling/).
+ * This class is used for [default error formatting](error-handling.md).
  * It converts PHP exceptions to [spec-compliant errors](https://facebook.github.io/graphql/#sec-Errors)
  * and provides tools for error debugging.
  */

src/Executor/ExecutionResult.php

@@ -5,7 +5,7 @@ use GraphQL\Error\Error;
 use GraphQL\Error\FormattedError;
 
 /**
- * Returned after [query execution](executing-queries/).
+ * Returned after [query execution](executing-queries.md).
  * Represents both - result of successful execution and of a failed one
  * (with errors collected in `errors` prop)
  *

src/Executor/Promise/PromiseAdapter.php

@@ -2,7 +2,7 @@
 namespace GraphQL\Executor\Promise;
 
 /**
- * Provides a means for integration of async PHP platforms ([related docs](data-fetching/#async-php))
+ * Provides a means for integration of async PHP platforms ([related docs](data-fetching.md#async-php))
  */
 interface PromiseAdapter
 {

src/GraphQL.php

@@ -18,7 +18,7 @@ use GraphQL\Validator\Rules\QueryComplexity;
 
 /**
  * This is the primary facade for fulfilling GraphQL operations.
- * See [related documentation](executing-queries/).
+ * See [related documentation](executing-queries.md).
  */
 class GraphQL
 {

src/Language/Parser.php

@@ -44,7 +44,7 @@ use GraphQL\Language\AST\VariableDefinitionNode;
 use GraphQL\Error\SyntaxError;
 
 /**
- * Parses string containing GraphQL query or [type definition](type-system/type-language/) to Abstract Syntax Tree.
+ * Parses string containing GraphQL query or [type definition](type-system/type-language.md) to Abstract Syntax Tree.
  */
 class Parser
 {

src/Language/Visitor.php

@@ -50,7 +50,7 @@ class VisitorOperation
  *     ]);
  *
  * Alternatively to providing enter() and leave() functions, a visitor can
- * instead provide functions named the same as the [kinds of AST nodes](reference/#graphqllanguageastnodekind),
+ * instead provide functions named the same as the [kinds of AST nodes](reference.md#graphqllanguageastnodekind),
  * or enter/leave visitors at a named key, leading to four permutations of
  * visitor API:
  *

src/Server/ServerConfig.php

@@ -9,7 +9,7 @@ use GraphQL\Utils\Utils;
 /**
  * Server configuration class.
  * Could be passed directly to server constructor. List of options accepted by **create** method is
- * [described in docs](executing-queries/#server-configuration-options).
+ * [described in docs](executing-queries.md#server-configuration-options).
  *
  * Usage example:
  *

src/Server/StandardServer.php

@@ -20,7 +20,7 @@ use Psr\Http\Message\StreamInterface;
  *     ]);
  *     $server->handleRequest();
  *
- * Or using [ServerConfig](reference/#graphqlserverserverconfig) instance:
+ * Or using [ServerConfig](reference.md#graphqlserverserverconfig) instance:
  *
  *     $config = GraphQL\Server\ServerConfig::create()
  *         ->setSchema($mySchema)
@@ -29,7 +29,7 @@ use Psr\Http\Message\StreamInterface;
  *     $server = new GraphQL\Server\StandardServer($config);
  *     $server->handleRequest();
  *
- * See [dedicated section in docs](executing-queries/#using-server) for details.
+ * See [dedicated section in docs](executing-queries.md#using-server) for details.
  *
  */
 class StandardServer

src/Type/Definition/ResolveInfo.php

@@ -13,7 +13,7 @@ use GraphQL\Utils\Utils;
 
 /**
  * Structure containing information useful for field resolution process.
- * Passed as 3rd argument to every field resolver. See [docs on field resolving (data fetching)](data-fetching/).
+ * Passed as 3rd argument to every field resolver. See [docs on field resolving (data fetching)](data-fetching.md).
  */
 class ResolveInfo
 {

src/Type/Schema.php

@@ -16,7 +16,7 @@ use GraphQL\Utils\TypeInfo;
 use GraphQL\Utils\Utils;
 
 /**
- * Schema Definition (see [related docs](type-system/schema/))
+ * Schema Definition (see [related docs](type-system/schema.md))
  *
  * A Schema is created by supplying the root types of each type of operation:
  * query, mutation (optional) and subscription (optional). A schema definition is

src/Type/SchemaConfig.php

@@ -9,7 +9,7 @@ use GraphQL\Utils\Utils;
 /**
  * Schema configuration class.
  * Could be passed directly to schema constructor. List of options accepted by **create** method is
- * [described in docs](type-system/schema/#configuration-options).
+ * [described in docs](type-system/schema.md#configuration-options).
  *
  * Usage example:
  *

src/Validator/DocumentValidator.php

@@ -58,9 +58,9 @@ use GraphQL\Validator\Rules\VariablesInAllowedPosition;
  * default list of rules defined by the GraphQL specification will be used.
  *
  * Each validation rule is an instance of GraphQL\Validator\Rules\AbstractValidationRule
- * which returns a visitor (see the [GraphQL\Language\Visitor API](reference/#graphqllanguagevisitor)).
+ * which returns a visitor (see the [GraphQL\Language\Visitor API](reference.md#graphqllanguagevisitor)).
  *
- * Visitor methods are expected to return an instance of [GraphQL\Error\Error](reference/#graphqlerrorerror),
+ * Visitor methods are expected to return an instance of [GraphQL\Error\Error](reference.md#graphqlerrorerror),
  * or array of such instances when invalid.
  *
  * Optionally a custom TypeInfo instance may be provided. If not provided, one