Add Docs

UPGRADE.md

@@ -1,4 +1,49 @@
-## Upgrade v0.10.x > dev-master
+## Upgrade v0.11.x > dev-master
+
+### Breaking: Descriptions in comments are not used as descriptions by default anymore
+Descriptions now need to be inside Strings or BlockStrings in order to be picked up as
+description. If you want to keep the old behaviour you can supply the option `commentDescriptions`
+to BuildSchema::buildAST(), BuildSchema::build() or Printer::doPrint().
+
+Here is the official way now to define descriptions in the graphQL language:
+
+Old:
+
+```graphql
+# Description
+type Dog {
+  ...
+}
+```
+
+New:
+
+```graphql
+"Description"
+type Dog {
+  ...
+}
+
+"""
+Long Description
+"""
+type Dog {
+  ...
+}
+```
+
+### Breaking: Custom types need to return `Utils::undefined()` or throw on invalid value
+As null might be a valid value custom types need to return now `Utils::undefined()` or throw an
+Exception inside `parseLiteral()`, `parseValue()` and `serialize()`. 
+
+Returning null from any of these methods will now be treated as valid result.
+
+### Breaking: TypeConfigDecorator was removed from BuildSchema
+TypeConfigDecorator was used as second argument in `BuildSchema::build()` and `BuildSchema::buildAST()` to
+enable generated schemas with Unions or Interfaces to be used for resolving. This was fixed in a more
+generalised approach so that the TypeConfigDecorator is not needed anymore and can be removed.
+
+The concrete Types are now resolved based on the `__typename` field.
 
 ### Possibly Breaking: AST to array serialization excludes nulls
 Most users won't be affected. It *may* affect you only if you do your own manipulations 

docs/reference.md

@@ -1352,7 +1352,7 @@ static function setWarningHandler(callable $warningHandler = null)
  * @api
  * @param bool|int $suppress
  */
-static function suppress($suppress = false)
+static function suppress($suppress = true)
 ```
 
 ```php
@@ -1367,7 +1367,7 @@ static function suppress($suppress = false)
  * @api
  * @param bool|int $enable
  */
-static function enable($enable = false)
+static function enable($enable = true)
 ```
 # GraphQL\Error\ClientAware
 This interface is used for [default error formatting](error-handling.md).
@@ -1697,7 +1697,7 @@ function setPersistentQueryLoader(callable $persistentQueryLoader)
  * @param bool|int $set
  * @return $this
  */
-function setDebug($set = false)
+function setDebug($set = true)
 ```
 
 ```php
@@ -1927,13 +1927,19 @@ See [section in docs](type-system/type-language.md) for details.
  * Given that AST it constructs a GraphQL\Type\Schema. The resulting schema
  * has no resolve methods, so execution will use default resolvers.
  *
+ * Accepts options as a second argument:
+ *
+ *    - commentDescriptions:
+ *        Provide true to use preceding comments as the description.
+ *
+ *
  * @api
  * @param DocumentNode $ast
- * @param callable $typeConfigDecorator
+ * @param array $options
  * @return Schema
  * @throws Error
  */
-static function buildAST(GraphQL\Language\AST\DocumentNode $ast, callable $typeConfigDecorator = null)
+static function buildAST(GraphQL\Language\AST\DocumentNode $ast, array $options = [])
 ```
 
 ```php
@@ -1943,10 +1949,10 @@ static function buildAST(GraphQL\Language\AST\DocumentNode $ast, callable $typeC
  *
  * @api
  * @param DocumentNode|Source|string $source
- * @param callable $typeConfigDecorator
+ * @param array $options
  * @return Schema
  */
-static function build($source, callable $typeConfigDecorator = null)
+static function build($source, array $options = [])
 ```
 # GraphQL\Utils\AST
 Various utilities dealing with AST
@@ -2049,6 +2055,32 @@ static function astFromValue($value, GraphQL\Type\Definition\InputType $type)
 static function valueFromAST($valueNode, GraphQL\Type\Definition\InputType $type, $variables = null)
 ```
 
+```php
+/**
+ * Produces a PHP value given a GraphQL Value AST.
+ *
+ * Unlike `valueFromAST()`, no type is provided. The resulting JavaScript value
+ * will reflect the provided GraphQL value AST.
+ *
+ * | GraphQL Value        | PHP Value     |
+ * | -------------------- | ------------- |
+ * | Input Object         | Assoc Array   |
+ * | List                 | Array         |
+ * | Boolean              | Boolean       |
+ * | String               | String        |
+ * | Int / Float          | Int / Float   |
+ * | Enum                 | Mixed         |
+ * | Null                 | null          |
+ *
+ * @api
+ * @param Node $valueNode
+ * @param array|null $variables
+ * @return mixed
+ * @throws \Exception
+ */
+static function valueFromASTUntyped($valueNode, array $variables = null)
+```
+
 ```php
 /**
  * Returns type definition for given AST Type node
@@ -2079,11 +2111,15 @@ Given an instance of Schema, prints it in GraphQL type language.
 **Class Methods:** 
 ```php
 /**
+ * Accepts options as a second argument:
+ *
+ *    - commentDescriptions:
+ *        Provide true to use preceding comments as the description.
  * @api
  * @param Schema $schema
  * @return string
  */
-static function doPrint(GraphQL\Type\Schema $schema)
+static function doPrint(GraphQL\Type\Schema $schema, array $options = [])
 ```
 
 ```php
@@ -2092,5 +2128,5 @@ static function doPrint(GraphQL\Type\Schema $schema)
  * @param Schema $schema
  * @return string
  */
-static function printIntrosepctionSchema(GraphQL\Type\Schema $schema)
+static function printIntrosepctionSchema(GraphQL\Type\Schema $schema, array $options = [])
 ```

docs/type-system/type-language.md

@@ -33,36 +33,11 @@ $contents = file_get_contents('schema.graphql');
 $schema = BuildSchema::build($contents);
 ```
 
-By default, such schema is created without any resolvers. As a result, it doesn't support **Interfaces** and **Unions**
+By default, such schema is created without any resolvers.
-because it is impossible to resolve actual implementations during execution.
 
-Also, we have to rely on [default field resolver](../data-fetching.md#default-field-resolver) and **root value** in 
+We have to rely on [default field resolver](../data-fetching.md#default-field-resolver) and **root value** in 
 order to execute a query against this schema.
 
-# Defining resolvers
-Since 0.10.0
-
-In order to enable **Interfaces**, **Unions** and custom field resolvers you can pass the second argument: 
-**type config decorator** to schema builder. 
-
-It accepts default type config produced by the builder and is expected to add missing options like 
-[**resolveType**](interfaces.md#configuration-options) for interface types or 
-[**resolveField**](object-types.md#configuration-options) for object types.
-
-```php
-<?php
-use GraphQL\Utils\BuildSchema;
-
-$typeConfigDecorator = function($typeConfig, $typeDefinitionNode) {
-    $name = $typeConfig['name'];
-    // ... add missing options to $typeConfig based on type $name
-    return $typeConfig;
-};
-
-$contents = file_get_contents('schema.graphql');
-$schema = BuildSchema::build($contents, $typeConfigDecorator);
-```
-
 # Performance considerations
 Since 0.10.0
 
@@ -89,4 +64,4 @@ if (!file_exists($cacheFilename)) {
 
 $typeConfigDecorator = function () {};
 $schema = BuildSchema::build($document, $typeConfigDecorator);
-```
+```