Better docs and comments on breaks and deprecations for 8.0

Author: vladar

UPGRADE.md

@@ -1,22 +1,14 @@
 # Upgrade
 
 ## Upgrade v0.7.x > v0.8.x
+All of those changes apply to those who extends various parts of this library.
+If you only use the library and don't try to extend it - everything should work without breaks.
 
-### AST node classes
-AST node classes were renamed to disambiguate with types. e.g.:
 
-```
-GraphQL\Language\AST\Field -> GraphQL\Language\AST\FieldNode
-GraphQL\Language\AST\OjbectValue -> GraphQL\Language\AST\OjbectValueNode
-```
-etc.
-
-Node kind constants were extracted from `GraphQL\Language\AST\Node` to `GraphQL\Language\AST\NodeKind`
-
-
-### Custom directives handling
+### Breaking: Custom directives handling
 When passing custom directives to schema, default directives (like `@skip` and `@include`) 
-are not added to schema automatically anymore. If you need them - add them explicitly with your other directives
+are not added to schema automatically anymore. If you need them - add them explicitly with 
+your other directives.
 
 Before the change:
 ```php
@@ -34,26 +26,31 @@ $schema = new Schema([
 ]);
 ```
 
-### Protected property and method naming
-In order to unify coding style, leading underscores were removed from all private and protected properties 
-and methods. 
+### Breaking: Schema protected property and methods visibility 
+Most of the `protected` properties and methods of `GraphQL\Schema` were changed to `private`.
+Please use public interface instead.
 
-Example before the change:
-```php
-GraphQL\Schema::$_queryType;
-```
+### Breaking: Node kind constants
+Node kind constants were extracted from `GraphQL\Language\AST\Node` to 
+separate class `GraphQL\Language\AST\NodeKind`
+
+### Non-breaking: AST node classes renamed
+AST node classes were renamed to disambiguate with types. e.g.:
 
-Correct usage after the change:
-```php
-GraphQL\Schema::$queryType;
 ```
+GraphQL\Language\AST\Field -> GraphQL\Language\AST\FieldNode
+GraphQL\Language\AST\OjbectValue -> GraphQL\Language\AST\OjbectValueNode
+```
+etc. 
 
-So if you rely on any protected properties or methods of any GraphQL class, make sure to 
-delete leading underscores.
+Old names are still available via `class_alias` defined in `src/deprecated.php`. 
+This file is included automatically when using composer autoloading.
 
 ### Deprecations
-There are also several deprecations which still work, but trigger `E_USER_DEPRECATED` 
-when used.
+There are several deprecations which still work, but trigger `E_USER_DEPRECATED` when used.
+
+For example `GraphQL\Executor\Executor::setDefaultResolveFn()` is renamed to `setDefaultResolver()`
+but still works with old name.
 
 ## Upgrade v0.6.x > v0.7.x
 

src/Error/FormattedError.php

@@ -14,7 +14,7 @@
 class FormattedError
 {
     /**
-     * @deprecated since 2016-10-21
+     * @deprecated as of 8.0
      * @param $error
      * @param SourceLocation[] $locations
      * @return array

src/Executor/Executor.php

@@ -894,7 +894,7 @@ private static function inferTypeOf($value, $context, ResolveInfo $info, Abstrac
     }
 
     /**
-     * @deprecated as of 19.11.2016
+     * @deprecated as of 8.0
      */
     public static function defaultResolveFn($source, $args, $context, ResolveInfo $info)
     {
@@ -903,7 +903,7 @@ public static function defaultResolveFn($source, $args, $context, ResolveInfo $i
     }
 
     /**
-     * @deprecated as of 19.11.2016
+     * @deprecated as of 8.0
      */
     public static function setDefaultResolveFn($fn)
     {

src/Executor/Values.php

@@ -162,7 +162,7 @@ public static function getArgumentValues($def, $node, $variableValues)
     }
 
     /**
-     * @deprecated Moved to Utils\AST::valueFromAST
+     * @deprecated as of 8.0 (Moved to Utils\AST::valueFromAST)
      *
      * @param $valueNode
      * @param InputType $type

src/Type/Definition/Directive.php

@@ -19,7 +19,7 @@ class Directive
 
     /**
      * @var array
-     * @deprecated as of 8.0 (use constants directly)
+     * @deprecated as of 8.0 (use DirectiveLocation constants directly)
      */
     public static $directiveLocations = [
         // Operations:

src/Type/Definition/FieldArgument.php

@@ -89,7 +89,6 @@ public function __construct(array $def)
 
     /**
      * @return InputType
-     * @deprecated in favor of setting 'fields' as closure per objectType vs on individual field/argument level
      */
     public function getType()
     {

src/Type/Definition/ResolveInfo.php

@@ -24,7 +24,7 @@ class ResolveInfo
 
     /**
      * @var FieldNode[]
-     * @deprecated Renamed to $fieldNodes as of 19.11.2016, will be removed after several releases
+     * @deprecated as of 8.0 (Renamed to $fieldNodes)
      */
     public $fieldASTs;