Improving docblock comments

src/Error/Warning.php

@@ -18,11 +18,27 @@ final class Warning
 
     static private $warningHandler;
 
+    /**
+     * Sets warning handler which (when set) will intercept all system warnings.
+     * When not set, trigger_error() is used to notify about warnings.
+     *
+     * @param callable|null $warningHandler
+     */
     public static function setWarningHandler(callable $warningHandler = null)
     {
         self::$warningHandler = $warningHandler;
     }
 
+    /**
+     * Suppress warning by id (has no effect when custom warning handler is set)
+     *
+     * Usage example:
+     * Warning::suppress(Warning::NOT_A_TYPE)
+     *
+     * When passing true - suppresses all warnings.
+     *
+     * @param bool|int $suppress
+     */
     static function suppress($suppress = true)
     {
         if (true === $suppress) {
@@ -35,6 +51,16 @@ final class Warning
         }
     }
 
+    /**
+     * Re-enable previously suppressed warning by id
+     *
+     * Usage example:
+     * Warning::suppress(Warning::NOT_A_TYPE)
+     *
+     * When passing true - re-enables all warnings.
+     *
+     * @param bool|int $enable
+     */
     public static function enable($enable = true)
     {
         if (true === $enable) {

src/Language/Parser.php

@@ -70,12 +70,12 @@ class Parser
     /**
      * Given a string containing a GraphQL value (ex. `[42]`), parse the AST for
      * that value.
-     * Throws GraphQLError if a syntax error is encountered.
+     * Throws GraphQL\Error\SyntaxError if a syntax error is encountered.
      *
      * This is useful within tools that operate upon GraphQL Values directly and
      * in isolation of complete GraphQL documents.
      *
-     * Consider providing the results to the utility function: valueFromAST().
+     * Consider providing the results to the utility function: GraphQL\Utils\AST::valueFromAST().
      *
      * @param Source|string $source
      * @param array $options
@@ -94,12 +94,13 @@ class Parser
     /**
      * Given a string containing a GraphQL Type (ex. `[Int!]`), parse the AST for
      * that type.
-     * Throws GraphQLError if a syntax error is encountered.
+     * Throws GraphQL\Error\SyntaxError if a syntax error is encountered.
      *
      * This is useful within tools that operate upon GraphQL Types directly and
      * in isolation of complete GraphQL documents.
      *
-     * Consider providing the results to the utility function: typeFromAST().
+     * Consider providing the results to the utility function: GraphQL\Utils\AST::typeFromAST().
+     *
      * @param Source|string $source
      * @param array $options
      * @return ListTypeNode|NameNode|NonNullTypeNode

src/Language/Printer.php

@@ -42,6 +42,12 @@ use GraphQL\Utils\Utils;
 
 class Printer
 {
+    /**
+     * Prints AST to string. Capable of printing GraphQL queries and Type definition language.
+     *
+     * @param Node $ast
+     * @return string
+     */
     public static function doPrint($ast)
     {
         static $instance;

src/Language/Visitor.php

@@ -18,7 +18,7 @@ class VisitorOperation
 class Visitor
 {
     /**
-     * Break visitor
+     * Returns marker for visitor break
      *
      * @return VisitorOperation
      */
@@ -30,7 +30,9 @@ class Visitor
     }
 
     /**
-     * Skip current node
+     * Returns marker for skipping current node
+     *
+     * @return VisitorOperation
      */
     public static function skipNode()
     {
@@ -40,7 +42,9 @@ class Visitor
     }
 
     /**
-     * Remove current node
+     * Returns marker for removing a node
+     *
+     * @return VisitorOperation
      */
     public static function removeNode()
     {
@@ -105,23 +109,23 @@ class Visitor
      * a new version of the AST with the changes applied will be returned from the
      * visit function.
      *
-     *     var editedAST = visit(ast, {
+     *     $editedAST = Visitor::visit($ast, [
-     *       enter(node, key, parent, path, ancestors) {
+     *       'enter' => function ($node, $key, $parent, $path, $ancestors) {
-     *         // @return
+     *         // return
-     *         //   undefined: no action
+     *         //   null: no action
-     *         //   false: skip visiting this node
+     *         //   Visitor::skipNode(): skip visiting this node
-     *         //   visitor.BREAK: stop visiting altogether
+     *         //   Visitor::stop(): stop visiting altogether
-     *         //   null: delete this node
+     *         //   Visitor::removeNode(): delete this node
      *         //   any value: replace this node with the returned value
      *       },
-     *       leave(node, key, parent, path, ancestors) {
+     *       'leave' => function ($node, $key, $parent, $path, $ancestors) {
-     *         // @return
+     *         // return
-     *         //   undefined: no action
+     *         //   null: no action
-     *         //   visitor.BREAK: stop visiting altogether
+     *         //   Visitor::stop(): stop visiting altogether
-     *         //   null: delete this node
+     *         //   Visitor::removeNode(): delete this node
      *         //   any value: replace this node with the returned value
      *       }
-     *     });
+     *     ]);
      *
      * Alternatively to providing enter() and leave() functions, a visitor can
      * instead provide functions named the same as the kinds of AST nodes, or
@@ -130,51 +134,57 @@ class Visitor
      *
      * 1) Named visitors triggered when entering a node a specific kind.
      *
-     *     visit(ast, {
+     *     Visitor::visit($ast, [
-     *       Kind(node) {
+     *       'Kind' => function ($node) {
      *         // enter the "Kind" node
      *       }
-     *     })
+     *     ]);
      *
      * 2) Named visitors that trigger upon entering and leaving a node of
      *    a specific kind.
      *
-     *     visit(ast, {
+     *     Visitor::visit($ast, [
-     *       Kind: {
+     *       'Kind' => [
-     *         enter(node) {
+     *         'enter' => function ($node) {
      *           // enter the "Kind" node
      *         }
-     *         leave(node) {
+     *         'leave' => function ($node) {
      *           // leave the "Kind" node
      *         }
-     *       }
+     *       ]
-     *     })
+     *     ]);
      *
      * 3) Generic visitors that trigger upon entering and leaving any node.
      *
-     *     visit(ast, {
+     *     Visitor::visit($ast, [
-     *       enter(node) {
+     *       'enter' => function ($node) {
      *         // enter any node
      *       },
-     *       leave(node) {
+     *       'leave' => function ($node) {
      *         // leave any node
      *       }
-     *     })
+     *     ]);
      *
      * 4) Parallel visitors for entering and leaving nodes of a specific kind.
      *
-     *     visit(ast, {
+     *     Visitor::visit($ast, [
-     *       enter: {
+     *       'enter' => [
-     *         Kind(node) {
+     *         'Kind' => function($node) {
      *           // enter the "Kind" node
      *         }
      *       },
-     *       leave: {
+     *       'leave' => [
-     *         Kind(node) {
+     *         'Kind' => function ($node) {
      *           // leave the "Kind" node
      *         }
-     *       }
+     *       ]
-     *     })
+     *     ]);
+     *
+     * @param Node $root
+     * @param array $visitor
+     * @param array $keyMap
+     * @return Node|mixed
+     * @throws \Exception
      */
     public static function visit($root, $visitor, $keyMap = null)
     {

src/Type/Definition/ResolveInfo.php

@@ -34,12 +34,12 @@ class ResolveInfo
     public $fieldNodes;
 
     /**
-     * @var OutputType
+     * @var ScalarType|ObjectType|InterfaceType|UnionType|EnumType|ListOfType|NonNull
      */
     public $returnType;
 
     /**
-     * @var Type|CompositeType
+     * @var ObjectType|InterfaceType|UnionType
      */
     public $parentType;
 
@@ -80,10 +80,9 @@ class ResolveInfo
     }
 
     /**
-     * Helper method that returns names of all fields selected in query for $this->fieldName up to $depth levels
+     * Helper method that returns names of all fields selected in query for
+     * $this->fieldName up to $depth levels
      *
-     *
-     * query AppHomeRoute{viewer{id,..._0c28183ce}} fragment _0c28183ce on Viewer{id,profile{firstName,id,locations{id}}}
      * Example:
      * query MyQuery{
      * {
@@ -98,7 +97,8 @@ class ResolveInfo
      *   }
      * }
      *
-     * Given this ResolveInfo instance is a part of "root" field resolution, and $depth === 1, method will return:
+     * Given this ResolveInfo instance is a part of "root" field resolution, and $depth === 1,
+     * method will return:
      * [
      *     'id' => true,
      *     'nested' => [

src/Type/Schema.php

@@ -170,6 +170,8 @@ class Schema
      * Returns array of all types in this schema. Keys of this array represent type names, values are instances
      * of corresponding type definitions
      *
+     * This operation requires full schema scan. Do not use in production environment.
+     *
      * @return Type[]
      */
     public function getTypeMap()
@@ -244,6 +246,8 @@ class Schema
      * Returns all possible concrete types for given abstract type
      * (implementations for interfaces and members of union type for unions)
      *
+     * This operation requires full schema scan. Do not use in production environment.
+     *
      * @param AbstractType $abstractType
      * @return ObjectType[]
      */
@@ -359,6 +363,10 @@ class Schema
     }
 
     /**
+     * Validates schema.
+     *
+     * This operation requires full schema scan. Do not use in production environment.
+     *
      * @throws InvariantViolation
      */
     public function assertValid()

src/Type/SchemaConfig.php

@@ -45,6 +45,8 @@ class SchemaConfig
     public $typeLoader;
 
     /**
+     * Converts an array of options to instance of SchemaConfig
+     *
      * @param array $options
      * @return SchemaConfig
      */

src/Validator/DocumentValidator.php

@@ -1,6 +1,7 @@
 <?php
 namespace GraphQL\Validator;
 
+use GraphQL\Error\Error;
 use GraphQL\Error\InvariantViolation;
 use GraphQL\Language\AST\ListValueNode;
 use GraphQL\Language\AST\DocumentNode;
@@ -54,6 +55,11 @@ class DocumentValidator
 
     private static $initRules = false;
 
+    /**
+     * Returns all validation rules
+     *
+     * @return callable[]
+     */
     public static function allRules()
     {
         if (!self::$initRules) {
@@ -104,6 +110,12 @@ class DocumentValidator
         return self::$defaultRules;
     }
 
+    /**
+     * Returns validation rule
+     *
+     * @param string $name
+     * @return callable|null
+     */
     public static function getRule($name)
     {
         $rules = static::allRules();
@@ -111,12 +123,45 @@ class DocumentValidator
         return isset($rules[$name]) ? $rules[$name] : null ;
     }
 
+    /**
+     * Add rule to list of default validation rules
+     *
+     * @param string $name
+     * @param callable $rule
+     */
     public static function addRule($name, callable $rule)
     {
         self::$rules[$name] = $rule;
     }
 
-    public static function validate(Schema $schema, DocumentNode $ast, array $rules = null, TypeInfo $typeInfo = null)
+    /**
+     * Implements the "Validation" section of the spec.
+     *
+     * Validation runs synchronously, returning an array of encountered errors, or
+     * an empty array if no errors were encountered and the document is valid.
+     *
+     * 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 rules is a function which returns a visitor
+     * (see the GraphQL\Language\Visitor API). Visitor methods are expected to return
+     * GraphQL\Error\Error, or arrays of GraphQL\Error\Error when invalid.
+     *
+     * Optionally a custom TypeInfo instance may be provided. If not provided, one
+     * will be created from the provided schema.
+     *
+     * @param Schema $schema
+     * @param DocumentNode $ast
+     * @param array|null $rules
+     * @param TypeInfo|null $typeInfo
+     * @return Error[]
+     */
+    public static function validate(
+        Schema $schema,
+        DocumentNode $ast,
+        array $rules = null,
+        TypeInfo $typeInfo = null
+    )
     {
         if (null === $rules) {
             $rules = static::allRules();