Restructure docs (#818)

Author: spawnia

.gitattributes

@@ -4,11 +4,14 @@
 /benchmarks export-ignore
 /tests export-ignore
 /examples export-ignore
-/tools export-ignore
 .codecov.yml export-ignore
 .gitattributes export-ignore
 .gitignore export-ignore
 CONTRIBUTING.md export-ignore
+generate-class-reference.php export-ignore
 mkdocs.yml export-ignore
 phpbench.json export-ignore
-phpunit.xml.dist  export-ignore
+phpcs.xml.dist export-ignore
+phpstan.neon.dist export-ignore
+phpstan-baseline.neon export-ignore
+phpunit.xml.dist export-ignore

CHANGELOG.md

@@ -264,20 +264,20 @@ This release brings several breaking changes. Please refer to [UPGRADE](UPGRADE.
 
 New features and notable changes:
 - Changed minimum PHP version from 5.4 to 5.5
-- Lazy loading of types without separate build step (see #69, see [docs](http://webonyx.github.io/graphql-php/type-system/schema/#lazy-loading-of-types))
-- PSR-7 compliant Standard Server (see [docs](http://webonyx.github.io/graphql-php/executing-queries/#using-server))
-- New default error formatting, which does not expose sensitive data (see [docs](http://webonyx.github.io/graphql-php/error-handling/))
-- Ability to define custom error handler to filter/log/re-throw exceptions after execution (see [docs](http://webonyx.github.io/graphql-php/error-handling/#custom-error-handling-and-formatting))
-- Allow defining schema configuration using objects with fluent setters vs array (see [docs](http://webonyx.github.io/graphql-php/type-system/schema/#using-config-class))
-- Allow serializing AST to array and re-creating AST from array lazily (see [docs](http://webonyx.github.io/graphql-php/reference/#graphqlutilsast))
-- [Apollo-style](https://dev-blog.apollodata.com/query-batching-in-apollo-63acfd859862) query batching support via server (see [docs](http://webonyx.github.io/graphql-php/executing-queries/#query-batching))
-- Schema validation, including validation of interface implementations (see [docs](http://webonyx.github.io/graphql-php/type-system/schema/#schema-validation))
-- Ability to pass custom config formatter when defining schema using [GraphQL type language](http://graphql.org/learn/schema/#type-language) (see [docs](http://webonyx.github.io/graphql-php/type-system/type-language/))
+- Lazy loading of types without separate build step (see #69, see [docs](https://webonyx.github.io/graphql-php/type-system/schema/#lazy-loading-of-types))
+- PSR-7 compliant Standard Server (see [docs](https://webonyx.github.io/graphql-php/executing-queries/#using-server))
+- New default error formatting, which does not expose sensitive data (see [docs](https://webonyx.github.io/graphql-php/error-handling/))
+- Ability to define custom error handler to filter/log/re-throw exceptions after execution (see [docs](https://webonyx.github.io/graphql-php/error-handling/#custom-error-handling-and-formatting))
+- Allow defining schema configuration using objects with fluent setters vs array (see [docs](https://webonyx.github.io/graphql-php/type-system/schema/#using-config-class))
+- Allow serializing AST to array and re-creating AST from array lazily (see [docs](https://webonyx.github.io/graphql-php/reference/#graphqlutilsast))
+- [Apollo-style](https://dev-blog.apollodata.com/query-batching-in-apollo-63acfd859862) query batching support via server (see [docs](https://webonyx.github.io/graphql-php/executing-queries/#query-batching))
+- Schema validation, including validation of interface implementations (see [docs](https://webonyx.github.io/graphql-php/type-system/schema/#schema-validation))
+- Ability to pass custom config formatter when defining schema using [GraphQL type language](http://graphql.org/learn/schema/#type-language) (see [docs](https://webonyx.github.io/graphql-php/type-system/type-language/))
 
 Improvements:
 - Significantly improved parser performance (see #137 and #128)
 - Support for PHP7 exceptions everywhere (see #127)
-- Improved [documentation](http://webonyx.github.io/graphql-php/) and docblock comments
+- Improved [documentation](https://webonyx.github.io/graphql-php/) and docblock comments
 
 Deprecations and breaking changes - see [UPGRADE](UPGRADE.md) document.
 

CONTRIBUTING.md

@@ -85,5 +85,5 @@ We document this library by rendering the Markdown files in [docs](docs) with [M
 Generate the class reference docs:
 
 ```sh
-composer api-docs
+composer docs
 ```

UPGRADE.md

@@ -459,7 +459,7 @@ GraphQL::executeAndReturnResult(/**/)
 But note that this is deprecated format and will be removed in future versions. 
 
 In general, if new default formatting doesn't work for you - just set [your own error
-formatter](http://webonyx.github.io/graphql-php/error-handling/#custom-error-handling-and-formatting).
+formatter](https://webonyx.github.io/graphql-php/error-handling/#custom-error-handling-and-formatting).
 
 ### Breaking: Validation rules now have abstract base class
 Previously any callable was accepted by DocumentValidator as validation rule. Now only instances of 
@@ -561,7 +561,7 @@ See https://github.com/webonyx/graphql-php/issues/148
 Use [new PSR-7 compliant implementation](docs/executing-queries.md#using-server) instead.
 
 ### Deprecated: experimental `GraphQL\Type\Resolution` interface and implementations
-Use schema [**typeLoader** option](docs/type-system/schema.md#lazy-loading-of-types) instead.
+Use schema [**typeLoader** option](docs/schema-definition.md#lazy-loading-of-types) instead.
 
 ### Non-breaking: usage on async platforms
 When using the library on async platforms use separate method `GraphQL::promiseToExecute()`. 

composer.json

@@ -48,10 +48,10 @@
     }
   },
   "scripts": {
-    "api-docs": "php tools/gendocs.php",
     "baseline": "phpstan --ansi --generate-baseline",
     "bench": "phpbench run",
     "check": "composer lint && composer stan && composer test",
+    "docs": "php generate-class-reference.php",
     "fix": "phpcbf",
     "lint": "phpcs",
     "stan": "phpstan --ansi",

docs/index.md renamed to docs/about.md

@@ -16,7 +16,6 @@ engineers. Various implementations of this specification were written
 Great overview of GraphQL features and benefits is presented on [the official website](http://graphql.org/). 
 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.5+, 7.0+). 
@@ -29,11 +28,11 @@ are used. Instead, it provides tools for creating rich API for your existing app
 
 Library features include:
 
- - Primitives to express your app as a [Type System](type-system/index.md)
+ - Primitives to express your app as a [Type System](type-definitions/introduction.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)
+ - Optional tools for [parsing schema definition language](schema-definition-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)
@@ -46,8 +45,8 @@ The first version of this library (v0.1) was released on August 10th 2015.
 
 The current version supports all features described by GraphQL specification 
 as well as some experimental features like 
-[Schema Language parser](type-system/type-language.md) and 
-[Schema printer](reference.md#graphqlutilsschemaprinter).
+[schema definition language](schema-definition-language.md) and 
+[schema printer](class-reference.md#graphqlutilsschemaprinter).
 
 Ready for real-world usage. 
 

docs/best-practices.md

@@ -422,7 +422,7 @@ const INPUT_FIELD_DEFINITION = "INPUT_FIELD_DEFINITION";
 # 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.md#configuration-options).
+[described in docs](type-definitions/schema-definition.md#configuration-options).
 
 Usage example:
 
@@ -549,7 +549,7 @@ function setDirectives(array $directives)
 
 ```php
 /**
- * @return callable(string $name):Type|null
+ * @return callable|null
  *
  * @api
  */
@@ -565,7 +565,7 @@ function getTypeLoader()
 function setTypeLoader(callable $typeLoader)
 ```
 # GraphQL\Type\Schema
-Schema Definition (see [related docs](type-system/schema.md))
+Schema Definition (see [related docs](type-definitions/schema-definition.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
@@ -601,11 +601,11 @@ function __construct($config)
  *
  * This operation requires full schema scan. Do not use in production environment.
  *
- * @return Type[]
+ * @return array<string, Type>
  *
  * @api
  */
-function getTypeMap()
+function getTypeMap(): array
 ```
 
 ```php
@@ -688,17 +688,46 @@ function getPossibleTypes(GraphQL\Type\Definition\Type $abstractType): array
 
 ```php
 /**
+ * Returns all types that implement a given interface type.
+ *
+ * This operations requires full schema scan. Do not use in production environment.
+ *
+ * @api
+ */
+function getImplementations(GraphQL\Type\Definition\InterfaceType $abstractType): GraphQL\Utils\InterfaceImplementations
+```
+
+```php
+/**
+ * @deprecated as of 14.4.0 use isSubType instead, will be removed in 15.0.0.
+ *
  * Returns true if object type is concrete type of given abstract type
  * (implementation for interfaces and members of union type for unions)
  *
  * @api
+ * @codeCoverageIgnore
  */
 function isPossibleType(
     GraphQL\Type\Definition\AbstractType $abstractType,
     GraphQL\Type\Definition\ObjectType $possibleType
 ): bool
 ```
 
+```php
+/**
+ * Returns true if the given type is a sub type of the given abstract type.
+ *
+ * @param UnionType|InterfaceType  $abstractType
+ * @param ObjectType|InterfaceType $maybeSubType
+ *
+ * @api
+ */
+function isSubType(
+    GraphQL\Type\Definition\AbstractType $abstractType,
+    GraphQL\Type\Definition\ImplementingType $maybeSubType
+): bool
+```
+
 ```php
 /**
  * Returns instance of directive by name
@@ -734,7 +763,7 @@ function assertValid()
 function validate()
 ```
 # GraphQL\Language\Parser
-Parses string containing GraphQL query or [type definition](type-system/type-language.md) to Abstract Syntax Tree.
+Parses string containing GraphQL query or [type definition](type-definitions/schema-definition-language.md) to Abstract Syntax Tree.
 
 Those magic functions allow partial parsing:
 
@@ -762,15 +791,15 @@ Those magic functions allow partial parsing:
 @method static NodeList<FieldDefinitionNode> fieldsDefinition(Source|string $source, bool[] $options = [])
 @method static NodeList<InputValueDefinitionNode> argumentsDefinition(Source|string $source, bool[] $options = [])
 @method static InterfaceTypeDefinitionNode interfaceTypeDefinition(Source|string $source, bool[] $options = [])
-@method static NamedTypeNode[] unionMemberTypes(Source|string $source, bool[] $options = [])
+@method static NodeList<NamedTypeNode> unionMemberTypes(Source|string $source, bool[] $options = [])
 @method static NodeList<EnumValueDefinitionNode> enumValuesDefinition(Source|string $source, bool[] $options = [])
 @method static InputObjectTypeDefinitionNode inputObjectTypeDefinition(Source|string $source, bool[] $options = [])
 @method static TypeExtensionNode typeExtension(Source|string $source, bool[] $options = [])
 @method static ScalarTypeExtensionNode scalarTypeExtension(Source|string $source, bool[] $options = [])
 @method static InterfaceTypeExtensionNode interfaceTypeExtension(Source|string $source, bool[] $options = [])
 @method static EnumTypeExtensionNode enumTypeExtension(Source|string $source, bool[] $options = [])
 @method static DirectiveDefinitionNode directiveDefinition(Source|string $source, bool[] $options = [])
-@method static DirectiveLocation directiveLocation(Source|string $source, bool[] $options = [])
+@method static NameNode directiveLocation(Source|string $source, bool[] $options = [])
 
 **Class Methods:** 
 ```php
@@ -928,7 +957,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.md#graphqllanguageastnodekind),
+instead provide functions named the same as the [kinds of AST nodes](class-reference.md#graphqllanguageastnodekind),
 or enter/leave visitors at a named key, leading to four permutations of
 visitor API:
 
@@ -1088,13 +1117,13 @@ Implements the "Evaluating requests" section of the GraphQL specification.
 /**
  * Executes DocumentNode against given $schema.
  *
- * Always returns ExecutionResult and never throws. All errors which occur during operation
- * execution are collected in `$result->errors`.
+ * Always returns ExecutionResult and never throws.
+ * All errors which occur during operation execution are collected in `$result->errors`.
  *
- * @param mixed|null               $rootValue
- * @param mixed|null               $contextValue
- * @param mixed[]|ArrayAccess|null $variableValues
- * @param string|null              $operationName
+ * @param mixed|null                    $rootValue
+ * @param mixed|null                    $contextValue
+ * @param array<mixed>|ArrayAccess|null $variableValues
+ * @param string|null                   $operationName
  *
  * @return ExecutionResult|Promise
  *
@@ -1118,10 +1147,10 @@ static function execute(
  *
  * Useful for async PHP platforms.
  *
- * @param mixed|null   $rootValue
- * @param mixed|null   $contextValue
- * @param mixed[]|null $variableValues
- * @param string|null  $operationName
+ * @param mixed|null        $rootValue
+ * @param mixed|null        $contextValue
+ * @param array<mixed>|null $variableValues
+ * @param string|null       $operationName
  *
  * @return Promise
  *
@@ -1343,9 +1372,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\ValidationRule
-which returns a visitor (see the [GraphQL\Language\Visitor API](reference.md#graphqllanguagevisitor)).
+which returns a visitor (see the [GraphQL\Language\Visitor API](class-reference.md#graphqllanguagevisitor)).
 
-Visitor methods are expected to return an instance of [GraphQL\Error\Error](reference.md#graphqlerrorerror),
+Visitor methods are expected to return an instance of [GraphQL\Error\Error](class-reference.md#graphqlerrorerror),
 or array of such instances when invalid.
 
 Optionally a custom TypeInfo instance may be provided. If not provided, one
@@ -1442,7 +1471,7 @@ const CATEGORY_INTERNAL = "internal";
  *
  * @api
  */
-function getLocations()
+function getLocations(): array
 ```
 
 ```php
@@ -1623,7 +1652,7 @@ Usage Example:
     ]);
     $server->handleRequest();
 
-Or using [ServerConfig](reference.md#graphqlserverserverconfig) instance:
+Or using [ServerConfig](class-reference.md#graphqlserverserverconfig) instance:
 
     $config = GraphQL\Server\ServerConfig::create()
         ->setSchema($mySchema)
@@ -1642,12 +1671,12 @@ See [dedicated section in docs](executing-queries.md#using-server) for details.
  * (e.g. during schema instantiation).
  *
  * @param Throwable $error
- * @param bool      $debug
+ * @param int       $debug
  * @param bool      $exitWhenDone
  *
  * @api
  */
-static function send500Error($error, $debug = false, $exitWhenDone = false)
+static function send500Error($error, $debug = "GraphQL\Error\DebugFlag::NONE", $exitWhenDone = false)
 ```
 
 ```php
@@ -2091,8 +2120,8 @@ function getOriginalInput($key)
 function isReadOnly()
 ```
 # GraphQL\Utils\BuildSchema
-Build instance of `GraphQL\Type\Schema` out of type language definition (string or parsed AST)
-See [section in docs](type-system/type-language.md) for details.
+Build instance of `GraphQL\Type\Schema` out of schema language definition (string or parsed AST)
+See [schema definition language docs](schema-definition-language.md) for details.
 
 **Class Methods:** 
 ```php
@@ -2101,7 +2130,7 @@ See [section in docs](type-system/type-language.md) for details.
  * document.
  *
  * @param DocumentNode|Source|string $source
- * @param bool[]                     $options
+ * @param array<string, bool>        $options
  *
  * @return Schema
  *
@@ -2127,7 +2156,7 @@ static function build($source, callable $typeConfigDecorator = null, array $opti
  *        Provide true to use preceding comments as the description.
  *        This option is provided to ease adoption and will be removed in v16.
  *
- * @param bool[] $options
+ * @param array<string, bool> $options
  *
  * @return Schema
  *
@@ -2306,7 +2335,7 @@ static function typeFromAST(GraphQL\Type\Schema $schema, $inputTypeNode)
 static function getOperation(GraphQL\Language\AST\DocumentNode $document, $operationName = null)
 ```
 # GraphQL\Utils\SchemaPrinter
-Given an instance of Schema, prints it in GraphQL type language.
+Given an instance of Schema, prints it in schema definition language.
 
 **Class Methods:** 
 ```php

docs/reference.md renamed to docs/class-reference.md

@@ -39,8 +39,9 @@ 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:
+Mutations are root fields that are allowed to have side effects, such as creating, updating or deleting data.
+In contrast to Query fields, the fields within the root Mutation type are executed serially.
+Otherwise, their definition and execution is identical to all other fields.
 
 ```graphql
 mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
@@ -82,7 +83,7 @@ returned after mutation. In our example mutation will return:
 
 # Type System
 Conceptually GraphQL type is a collection of fields. Each field in turn
-has it's own type which allows to build complex hierarchies.
+has its own type which allows building complex hierarchies.
 
 Quick example on pseudo-language:
 ```