Docblocks improvements

Author: vladar

src/Type/Definition/DirectiveLocation.php

@@ -1,6 +1,9 @@
 <?php
 namespace GraphQL\Type\Definition;
 
+/**
+ * List of available directive locations
+ */
 class DirectiveLocation
 {
     const IFACE = 'INTERFACE';

src/Type/Definition/Type.php

@@ -70,7 +70,7 @@ public static function float()
 
     /**
      * @api
-     * @param ObjectType|InterfaceType|UnionType|ScalarType|InputObjectType|EnumType $wrappedType
+     * @param ObjectType|InterfaceType|UnionType|ScalarType|InputObjectType|EnumType|ListOfType|NonNull $wrappedType
      * @return ListOfType
      */
     public static function listOf($wrappedType)
@@ -80,7 +80,7 @@ public static function listOf($wrappedType)
 
     /**
      * @api
-     * @param ObjectType|InterfaceType|UnionType|ScalarType|InputObjectType|EnumType $wrappedType
+     * @param ObjectType|InterfaceType|UnionType|ScalarType|InputObjectType|EnumType|ListOfType $wrappedType
      * @return NonNull
      */
     public static function nonNull($wrappedType)

src/Utils/AST.php

@@ -35,8 +35,7 @@
 use GraphQL\Utils\Utils;
 
 /**
- * Class AST
- * @package GraphQL\Utils
+ * Various utilities dealing with AST
  */
 class AST
 {
@@ -59,8 +58,9 @@ class AST
      * Will produce instance of `ListValueNode` where `values` prop is a lazily-evaluated `NodeList`
      * returning instances of `StringValueNode` on access.
      *
-     * This is a reverse operation for $node->toArray(true)
+     * This is a reverse operation for AST::toArray($node)
      *
+     * @api
      * @param array $node
      * @return Node
      */
@@ -98,6 +98,7 @@ public static function fromArray(array $node)
     /**
      * Convert AST node to serializable array
      *
+     * @api
      * @param Node $node
      * @return array
      */
@@ -124,6 +125,7 @@ public static function toArray(Node $node)
      * | Mixed         | Enum Value           |
      * | null          | NullValue            |
      *
+     * @api
      * @param $value
      * @param InputType $type
      * @return ObjectValueNode|ListValueNode|BooleanValueNode|IntValueNode|FloatValueNode|EnumValueNode|StringValueNode|NullValueNode
@@ -267,8 +269,9 @@ static function astFromValue($value, InputType $type)
      * | String               | String        |
      * | Int / Float          | Int / Float   |
      * | Enum Value           | Mixed         |
-     * | Null Value           | stdClass      | instance of NullValue::getNullValue()
+     * | Null Value           | null          |
      *
+     * @api
      * @param $valueNode
      * @param InputType $type
      * @param null $variables
@@ -396,6 +399,9 @@ public static function valueFromAST($valueNode, InputType $type, $variables = nu
     }
 
     /**
+     * Returns type definition for given AST Type node
+     *
+     * @api
      * @param Schema $schema
      * @param NamedTypeNode|ListTypeNode|NonNullTypeNode $inputTypeNode
      * @return Type
@@ -430,6 +436,9 @@ private static function isMissingVariable($valueNode, $variables)
     }
 
     /**
+     * Returns operation type ("query", "mutation" or "subscription") given a document and operation name
+     *
+     * @api
      * @param DocumentNode $document
      * @param string $operationName
      * @return bool

src/Utils/BuildSchema.php

@@ -33,8 +33,8 @@
 use GraphQL\Type\Introspection;
 
 /**
- * Class BuildSchema
- * @package GraphQL\Utils
+ * 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.
  */
 class BuildSchema
 {
@@ -72,9 +72,10 @@ private function getNamedTypeNode(TypeNode $typeNode)
      * If no schema definition is provided, then it will look for types named Query
      * and Mutation.
      *
-     * Given that AST it constructs a GraphQLSchema. The resulting schema
+     * Given that AST it constructs a GraphQL\Type\Schema. The resulting schema
      * has no resolve methods, so execution will use default resolvers.
      *
+     * @api
      * @param DocumentNode $ast
      * @param callable $typeConfigDecorator
      * @return Schema
@@ -608,6 +609,7 @@ public function getDescription($node)
      * A helper function to build a GraphQLSchema directly from a source
      * document.
      * 
+     * @api
      * @param DocumentNode|Source|string $source
      * @param callable $typeConfigDecorator
      * @return Schema

src/Utils/SchemaPrinter.php

@@ -14,18 +14,27 @@
 use GraphQL\Type\Definition\Directive;
 
 /**
- * Class SchemaPrinter
- * @package GraphQL\Utils
+ * Given an instance of Schema, prints it in GraphQL type language.
  */
 class SchemaPrinter
 {
+    /**
+     * @api
+     * @param Schema $schema
+     * @return string
+     */
     public static function doPrint(Schema $schema)
     {
         return self::printFilteredSchema($schema, function($n) {
             return !self::isSpecDirective($n);
         }, 'self::isDefinedType');
     }
 
+    /**
+     * @api
+     * @param Schema $schema
+     * @return string
+     */
     public static function printIntrosepctionSchema(Schema $schema)
     {
         return self::printFilteredSchema($schema, [__CLASS__, 'isSpecDirective'], [__CLASS__, 'isIntrospectionType']);

tools/gendocs.php

@@ -8,6 +8,8 @@
 $entries = [
     \GraphQL\GraphQL::class,
     \GraphQL\Type\Definition\Type::class,
+    \GraphQL\Type\Definition\ResolveInfo::class,
+    \GraphQL\Type\Definition\DirectiveLocation::class => ['constants' => true],
     \GraphQL\Type\SchemaConfig::class,
     \GraphQL\Type\Schema::class,
     \GraphQL\Language\Parser::class,
@@ -17,7 +19,6 @@
     \GraphQL\Executor\Executor::class,
     \GraphQL\Executor\ExecutionResult::class,
     \GraphQL\Executor\Promise\PromiseAdapter::class,
-    \GraphQL\Type\Definition\ResolveInfo::class,
     \GraphQL\Validator\DocumentValidator::class,
     \GraphQL\Error\Error::class => ['constants' => true, 'methods' => true, 'props' => true],
     \GraphQL\Error\Warning::class => ['constants' => true, 'methods' => true],
@@ -27,7 +28,10 @@
     \GraphQL\Server\StandardServer::class,
     \GraphQL\Server\ServerConfig::class,
     \GraphQL\Server\Helper::class,
-    \GraphQL\Server\OperationParams::class
+    \GraphQL\Server\OperationParams::class,
+    \GraphQL\Utils\BuildSchema::class,
+    \GraphQL\Utils\AST::class,
+    \GraphQL\Utils\SchemaPrinter::class
 ];
 
 function renderClassMethod(ReflectionMethod $method) {