Work in progress on better docs (added docs for field arguments and input types)

docs/type-system/index.md

@@ -5,7 +5,7 @@ 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](object-types/).
+But most of the types in your schema will be [object types](/type-system/object-types/).
 
 # Type Definition Styles
 Several styles of type definitions are supported depending on your preferences.
@@ -155,4 +155,4 @@ Obviously you can automate this registry as you wish to reduce boilerplate or ev
 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 `MyTypes::myAType()` in your type definitions.
+to pass it in constructor - instead just use use `TypeRegistry::myAType()` in your type definitions.

docs/type-system/input-types.md

@@ -0,0 +1,119 @@
+# About Input and Output Types
+GraphQL receives data from clients via [Field Arguments](object-types/#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 
+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/), 
+[Interface](interfaces/), [Union](unions/)
+
+* **Input** types (or argument types) are: [Scalar](scalar-types/), [Enum](enum-types/), InputObject
+
+Obviously [NonNull and List](lists-and-nonnulls/) 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 
+[Enum](enum-types/) 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.
+
+# Input Object Type
+GraphQL specification defines Input Object Type for complex inputs. It is similar to ObjectType
+except that it's fields have no **args** or **resolve** options and their **type** must be input type.
+
+In **graphql-php** Input Object Type is an instance of `GraphQL\Type\Definition\InputObjectType` 
+(or one of it subclasses) which accepts configuration array in constructor:
+
+```php
+$filters = new InputObjectType([
+    'name' => 'StoryFiltersInput',
+    'fields' => [
+        'author' => [
+            'type' => Type::id(),
+            'description' => 'Only show stories with this author id'
+        ],
+        'popular' => [
+            'type' => Type::boolean(),
+            'description' => 'Only show popular stories (liked by several people)'
+        ],
+        'tags' => [
+            'type' => Type::listOf(Type::string()),
+            'description' => 'Only show stories which contain all of those tags'
+        ]
+    ]
+]);
+```
+
+Every field may be of other InputObjectType (thus complex hierarchies of inputs are possible)
+
+# Configuration options
+Constructor of InputObjectType accepts array with only 3 options:
+ 
+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 below).
+description  | `string` | Plain-text description of this type for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
+
+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)
+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
+
+# Using Input Object Type
+In the example above we defined our InputObjectType. Now let's use it in one of field arguments:
+
+```php
+$queryType = new ObjectType([
+    'name' => 'Query',
+    'fields' => [
+        'stories' => [
+            'type' => Type::listOf($storyType),
+            'args' => [
+                'filters' => [
+                    'type' => Type::nonNull($filters),
+                    'defaultValue' => [
+                        'popular' => true
+                    ]
+                ]
+            ],
+            'resolve' => function($rootValue, $args) {
+                return DataSource::filterStories($args['filters']);
+            }
+        ]
+    ]
+]);
+```
+(note that you can define **defaultValue** for fields with complex inputs as associative array).
+
+Then GraphQL query could include filters as literal value:
+```graphql
+{
+    stories(filters: {author: "1", popular: false})
+}
+```
+
+Or as query variable:
+```graphql
+query($filters: StoryFiltersInput!) {
+    stories(filters: $filters)
+}
+```
+```php
+$variables = [
+    'filters' => [
+        "author" => "1",
+        "popular" => false
+    ]
+];
+```
+
+**graphql-php** will validate the input against your InputObjectType definition and pass it to your 
+resolver as `$args['filters']`

docs/type-system/object-types.md

@@ -77,16 +77,26 @@ 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 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](#) below)
 type | `Type` | **Required.** Instance of internal or custom type. Note: type must be represented by single instance within schema (see also [Type Registry](#))
-args | `array` | Array of possible type arguments. Each entry is expected to be an array with keys: **name**, **type**, **description**, **defaultValue**
+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
-description | `string` | Plain-text description of this field description for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
+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)
 
- 
+# Field arguments
+Every field on a GraphQL object type can have zero or more arguments, defined in **args** option of field definition.
+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)
+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
+
 # Shorthand field definitions
-Fields can be also defined in **shorthand** notation (without `description`, `args` and `defaultValue`):
+Fields can be also defined in **shorthand** notation (with only **name** and **type** options):
 ```php
 'fields' => [
     'id' => Type::id(),

mkdocs.yml

@@ -2,7 +2,7 @@ site_name: graphql-php
 pages:
 - About: index.md
 - Getting Started: getting-started.md
-- Schema Definition:
+- Type System:
   - Introduction: type-system/index.md
   - Object Types: type-system/object-types.md
   - Scalar Types: type-system/scalar-types.md
@@ -10,6 +10,7 @@ pages:
   - Lists and Non-Null: type-system/lists-and-nonnulls.md
   - Interfaces: type-system/interfaces.md
   - Unions: type-system/unions.md
+  - Input Types: type-system/input-types.md
   - Defining Schema: type-system/schema.md
   - Custom Metadata: type-system/metadata.md
 - Data Fetching: data-fetching.md