Enum descriptions and deprecation support (#606)

* Fix EnumType exception message

* Add description support to enum type

* Add deprecation support to enum type

Author: mdoelker

src/Mappers/Root/EnumTypeMapper.php

@@ -10,6 +10,7 @@
 use GraphQL\Type\Definition\Type as GraphQLType;
 use MyCLabs\Enum\Enum;
 use phpDocumentor\Reflection\DocBlock;
+use phpDocumentor\Reflection\DocBlockFactory;
 use phpDocumentor\Reflection\Type;
 use phpDocumentor\Reflection\Types\Object_;
 use ReflectionClass;
@@ -119,7 +120,35 @@ private function mapByClassName(string $enumClass): EnumType|null
             $reflectionEnum->isBacked() &&
             (string) $reflectionEnum->getBackingType() === 'string';
 
-        $type = new EnumType($enumClass, $typeName, $useValues);
+        $docBlockFactory = DocBlockFactory::createInstance();
+
+        $enumDescription = null;
+        $docComment = $reflectionEnum->getDocComment();
+        if ($docComment) {
+            $docBlock = $docBlockFactory->create($docComment);
+            $enumDescription = $docBlock->getSummary();
+        }
+
+        $enumCaseDescriptions = [];
+        $enumCaseDeprecationReasons = [];
+        foreach ($reflectionEnum->getCases() as $reflectionEnumCase) {
+            $docComment = $reflectionEnumCase->getDocComment();
+            if ($docComment) {
+                $docBlock = $docBlockFactory->create($docComment);
+                $enumCaseDescription = $docBlock->getSummary();
+
+                $enumCaseDescriptions[$reflectionEnumCase->getName()] = $enumCaseDescription;
+                $deprecation = $docBlock->getTagsByName('deprecated')[0] ?? null;
+
+                if ($deprecation) {
+                    $enumCaseDeprecationReasons[$reflectionEnumCase->getName()] = (string) $deprecation;
+                }
+            }
+        }
+
+        /** @var array<string, string> $enumCaseDescriptions */
+        /** @var array<string, string> $enumCaseDeprecationReasons */
+        $type = new EnumType($enumClass, $typeName, $enumDescription, $enumCaseDescriptions, $enumCaseDeprecationReasons, $useValues);
 
         return $this->cacheByName[$type->name] = $this->cache[$enumClass] = $type;
     }

src/Types/EnumType.php

@@ -17,19 +17,37 @@
  */
 class EnumType extends BaseEnumType
 {
-    /** @param class-string<UnitEnum> $enumName */
-    public function __construct(string $enumName, string $typeName, private readonly bool $useValues = false)
-    {
-        $values = [];
+    /**
+     * @param class-string<UnitEnum> $enumName
+     * @param array<string, string> $caseDescriptions
+     * @param array<string, string> $caseDeprecationReasons
+     */
+    public function __construct(
+        string $enumName,
+        string $typeName,
+        ?string $description,
+        array $caseDescriptions,
+        array $caseDeprecationReasons,
+        private readonly bool $useValues = false,
+    ) {
+        $typeValues = [];
         foreach ($enumName::cases() as $case) {
-            /** @var UnitEnum $case */
-            $values[$this->serialize($case)] = ['value' => $case];
+            $key = $this->serialize($case);
+            $typeValues[$key] = [
+                'name' => $key,
+                'value' => $case,
+                'description' => $caseDescriptions[$case->name] ?? null,
+                'deprecationReason' => $caseDeprecationReasons[$case->name] ?? null,
+            ];
         }
 
-        parent::__construct([
-            'name' => $typeName,
-            'values' => $values,
-        ]);
+        parent::__construct(
+            [
+                'name' => $typeName,
+                'values' => $typeValues,
+                'description' => $description,
+            ]
+        );
     }
 
     // phpcs:disable SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
@@ -38,7 +56,7 @@ public function __construct(string $enumName, string $typeName, private readonly
     public function serialize($value): string
     {
         if (! $value instanceof UnitEnum) {
-            throw new InvalidArgumentException('Expected a Myclabs Enum instance');
+            throw new InvalidArgumentException('Expected a UnitEnum instance');
         }
 
         if (! $this->useValues) {