Work in progress on better docs (minor changes)

docs/executing-queries.md

@@ -1,6 +1,6 @@
 # Overview
 Query execution is a complex process involving multiple steps, including query **parsing**, 
-**validating** and finally **executing** against your schema.
+**validating** and finally **executing** against your [schema](type-system/schema/).
 
 **graphql-php** provides convenient facade for this process in class `GraphQL\GraphQL`:
 
@@ -34,12 +34,11 @@ contextValue  | `mixed` | Any value that holds information shared between all fi
 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.
 
+# Parsing
 Following reading describes implementation details of query execution process. It may clarify some 
 internals of GraphQL but is not required in order to use it. Feel free to skip to next section 
 on [Error Handling](error-handling/) for essentials.
 
-
-# Parsing
 TODOC
 
 # Validating

docs/type-system/index.md

@@ -1,5 +1,5 @@
 # Type System
-To start using GraphQL you are expected to implement a Type system. 
+To start using GraphQL you are expected to implement a type hierarchy and expose it as [Schema](type-system/schema/). 
 
 In **graphql-php** `type` is an instance of internal class from 
 `GraphQL\Type\Definition` namespace: `ScalarType`, `ObjectType`, `InterfaceType`, 
@@ -156,10 +156,3 @@ introduce Dependency Injection Container if your types have other dependencies.
 
 Alternatively all methods of registry could be static if you prefer - then there is no need
 to pass it in constructor - instead just use use `TypeRegistry::myAType()` in your type definitions.
-
-# Custom Metadata
-All types in **graphql-php** accept configuration array. In some cases you may be interested in 
-passing your own metadata for type or field definition.
-
-**graphql-php** preserves original configuration array in every type or field instance in 
-public property `$config`. Use it to implement app-level mappings and definitions.

docs/type-system/object-types.md

@@ -195,4 +195,11 @@ Field resolution is the primary mechanism in **graphql-php** for returning actua
 It is implemented using `resolveField` callback in type definition or `resolve`
 callback in field definition (which has precedence).
 
-Read section on [Data Fetching]() for complete description of this process.
+Read section on [Data Fetching]() for complete description of this process.
+
+# Custom Metadata
+All types in **graphql-php** accept configuration array. In some cases you may be interested in 
+passing your own metadata for type or field definition.
+
+**graphql-php** preserves original configuration array in every type or field instance in 
+public property `$config`. Use it to implement app-level mappings and definitions.

docs/type-system/schema.md

@@ -1,7 +1,6 @@
 # Schema Definition
-
-After all of your types are defined, you must define schema. Schema is a container for your type 
-hierarchy, which expects root type in constructor.
+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\Schema` which accepts configuration array 
 in constructor:
@@ -12,25 +11,16 @@ $schema = new Schema([
     'mutation' => $mutationType,
 ]);
 ```
-
-# Configuration Options
-
-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]`
-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.
-
+See possible constructor options [below](#configuration-options)
 
 # Query and Mutation types
-Schema consists of two special root types:
+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 containing root-level fields of your API:
+Query and Mutation types are regular [object types](object-types/) containing root-level fields 
+of your API:
 
 ```php
 use GraphQL\Type\Definition\ObjectType;
@@ -64,13 +54,13 @@ $mutationType = new ObjectType([
     'name' => 'Mutation',
     'fields' => [
         'createReviewForEpisode' => [
-            'type' => $createReviewForEpisode,
+            'type' => $createReviewForEpisodeMutation,
             'args' => [
                 'episode' => $episodeEnum,
                 'review' => $reviewInputObject
             ],
-            'resolve' => function() {
-                
+            'resolve' => function($val, $args) {
+                // TODOC
             }
         ]
     ]
@@ -78,11 +68,20 @@ $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, and their fields work exactly the same way.
+those types are the same as any other [object type](object-types/), and their fields work 
+exactly the same way.
 
-Resolvers of those fields receive `$rootValue` which you pass into execute call:
-`GraphQL::execute($schema, $query, $rootValue)`
-
-`Mutation` type is also just a regular object type. The difference is in semantics. 
+**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).
+
+# Configuration Options
+Schema constructor expects an array with following options:
+
+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]`
+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.

mkdocs.yml

@@ -12,7 +12,7 @@ pages:
   - Unions: type-system/unions.md
   - Input Types: type-system/input-types.md
   - Directives: type-system/directives.md
-  - Defining Schema: type-system/schema.md
+  - Schema: type-system/schema.md
 - Executing Queries: executing-queries.md
 - Handling Errors: error-handling.md
 - Fetching Data: data-fetching.md