feat: explicit description attribute (+ #[EnumValue]) + SchemaFactory docblock toggle (#793)

* feat: explicit description attribute + SchemaFactory docblock toggle

Adds explicit `description` argument to every schema-defining attribute
(Query, Mutation, Subscription, Type, ExtendType, Factory) and a
SchemaFactory toggle to disable the docblock-as-description fallback.

Addresses #453 and the type-level portion of #740.

Behaviour highlights:
- Explicit attribute description always wins; `''` deliberately blocks
  the docblock fallback; `null` falls through when the toggle is on.
- `setDocblockDescriptionsEnabled(false)` suppresses every docblock
  fallback path so internal developer docblocks stop leaking to public
  schema consumers.
- Duplicate descriptions across `#[Type]` + `#[ExtendType]` (or multiple
  `#[ExtendType]`s on the same class) now throw a
  DuplicateDescriptionOnTypeException naming every offending source.
- `InputTypeGenerator::mapFactoryMethod()` closes the long-standing
  `// TODO: add comment argument.` — factory-produced input types now
  participate in description resolution.

Consistency renames (breaking):
- `QueryFieldDescriptor`/`InputFieldDescriptor` `$comment` -> `$description`
  and paired method renames (getDescription/withDescription/
  withAddedDescriptionLines).
- `AbstractRequest` -> `AbstractGraphQLElement`
  and `AnnotationReader::getRequestAnnotation()` ->
  `getGraphQLElementAnnotation()`. The new name reflects the class's
  role as the shared base for GraphQL schema-element attributes.

Tests: +26 new (resolver precedence matrix, per-attribute integration,
conflict exception, docblock-off regression). Full suite 528 passing
across cs-check, phpstan, and phpunit.

* feat: #[EnumValue] attribute for per-case enum metadata

Closes the deeper portion of #740 that the original PR left as future work:
native PHP 8.1+ enum cases can now carry an explicit GraphQL description
and deprecation reason without relying on docblock parsing.

```php
#[Type]
enum Genre: string
{
    #[EnumValue(description: 'Fiction works including novels and short stories.')]
    case Fiction = 'fiction';

    #[EnumValue(deprecationReason: 'Use Fiction::Verse instead.')]
    case Poetry = 'poetry';
}
```

Naming: follows the GraphQL specification's term ("enum values", §3.5.2,
`__EnumValue`, `enumValues`) rather than the PHP language term "case".
This matches every other graphqlite attribute (`Type`, `Field`, `Query`,
`ExtendType`, …) which mirrors GraphQL spec names, and webonyx/graphql-php's
internal `EnumValueDefinition`. Targets `Attribute::TARGET_CLASS_CONSTANT`
so it applies to PHP enum cases.

Precedence: explicit `description` / `deprecationReason` on the attribute
win over docblock summary / `@deprecated` tag. Passing `''` deliberately
suppresses the fallback at that site, matching every other `description`
argument across the library. No-attribute cases continue to fall back to
docblock — BC preserved.

Adds `AnnotationReader::getEnumValueAnnotation(ReflectionEnumUnitCase)`
helper and threads it through `EnumTypeMapper::mapByClassName()` where
enum case metadata is aggregated.

Tests: 5 new unit tests (attribute defaults / description / deprecation
reason / both / empty string) plus 4 new integration tests over a new
fixture enum (attribute-supplied description, docblock fallback, explicit
deprecation, toggle-off suppresses docblock-only case). Full suite
537/537 green across cs-check, phpstan, and phpunit.

* feat: deprecation notice for enum cases missing #[EnumValue]

Announces the upcoming opt-in migration for PHP enums mapped to GraphQL
enum types. Today every case is automatically exposed; a future major
release will require #[EnumValue] on each case that should participate
in the schema, matching the opt-in model #[Field] already uses for
methods and properties on object types.

The practical win is selective exposure: an internal enum case can opt
out of the public schema simply by omitting #[EnumValue], instead of
forcing schema authors to split an enum or rename cases.

Runtime behaviour is unchanged. When an enum annotated with #[Type]
exposes any case without an #[EnumValue] attribute, EnumTypeMapper
emits an E_USER_DEPRECATED notice that names the specific cases so the
migration path is mechanical — matching graphqlite's existing
deprecation pattern (e.g. addControllerNamespace, setGlobTTL).

Tests: +1 explicit deprecation assertion (using PHPUnit 11's
expectUserDeprecationMessageMatches). Existing integration tests that
exercise the Genre fixture surface the notice via PHPUnit's deprecation
reporting, confirming the warning fires in realistic scenarios. Full
suite 538/538 green across cs-check, phpstan, and phpunit; 4 intentional
deprecation events reported.

Docs: descriptions.md gains a "Future migration" subsection describing
the planned opt-in model and the current advisory notice.

* docs: clarify runtime behaviour for unmapped enum cases after future flip

The advisory deprecation already announces the opt-in migration. Add a
second paragraph spelling out what happens if a resolver returns a case
that lacks #[EnumValue] after the default flips: webonyx/graphql-php's
native enum serialization rejects it, the same spec-compliant behaviour
that applies to any unknown enum value. That is the mechanism that makes
selective exposure safe — internal cases cannot leak via a resolver —
and clarifies that omitting #[EnumValue] is a deliberate 'do not expose
this value' signal, not an oversight to work around.

* fix: narrow enum advisory to fire only when zero cases carry #[EnumValue]

Partial annotation is the mechanism that will hide internal cases from
the public schema once the default flips to opt-in; leaving some cases
unannotated is deliberate and must not produce a warning. Under the
previous logic the advisory fired for every partial annotation, which
would punish exactly the pattern the migration encourages.

New rule: fire the E_USER_DEPRECATED advisory only when a #[Type]-mapped
enum declares zero #[EnumValue] attributes across all its cases — the
signal that the developer has not yet engaged with the opt-in model.
Annotating even a single case acknowledges the migration and silences
the notice; from that point any combination of annotated and unannotated
cases is correct and intentional.

Implementation: EnumTypeMapper::mapByClassName() now tracks a single
`sawAnyEnumValueAttribute` flag while iterating cases and emits the
notice only when the flag stays false. Message rewritten to explain the
"at least one case" requirement and point the reader at the intended
migration path — including the fact that a bare #[EnumValue] on a
single case is a valid acknowledgement.

Tests:
- Replaces the previous "any case missing" assertion with
  testEnumWithZeroEnumValueAttributesTriggersDeprecation using a new
  DescriptionLegacyEnum/Era fixture that declares no #[EnumValue] at
  all.
- Adds testEnumWithPartialEnumValueAttributesIsSilent to lock in the
  partial-annotation contract against regressions.
- Pre-existing Color/Size/Position fixtures gain a bare #[EnumValue] on
  their first case so their integration tests stop triggering the
  advisory — demonstrates the minimal upgrade path recommended in the
  docs.

Full suite 539/539 green across cs-check, phpstan, and phpunit, with
exactly 1 intentional deprecation coming from the dedicated advisory
test. The docs in descriptions.md are updated to reflect the corrected
semantics — "partial annotation is intentional and silent".

* docs: trim the enum migration subsection — short-lived transitional content

* refactor: sawAnyEnumValueAttribute -> hasEnumValueAttribute

Matches PHP's isser/haser naming convention and reads as a present-state
question instead of imperative history. Also aligns the private helper
name with the boolean semantics (plural -> singular since the check is
'has at least one attribute anywhere on the enum').

* docs: drop the 'bare single #[EnumValue] to silence' shortcut recommendation

Recommending users annotate a single case to silence the advisory is
actively misleading: once the default flips, every other case would
disappear from the schema — the exact opposite of what a user reaching
for the shortcut wanted. The honest recommendation is 'annotate every
case you want to keep exposed', which aligns their intent with the
post-flip behaviour.

- Warning message rewritten around 'add to every case you want exposed,
  omit only from cases you want hidden' instead of 'at least one case
  silences this notice'.
- descriptions.md migration subsection mirrors the same framing.
- Color/Size/Position test fixtures now annotate every case, not just
  the first one, so they demonstrate the correct migration pattern
  rather than the misleading shortcut.

Author: oojacoboo

src/AnnotationReader.php

@@ -5,11 +5,13 @@
 namespace TheCodingMachine\GraphQLite;
 
 use ReflectionClass;
+use ReflectionEnumUnitCase;
 use ReflectionMethod;
 use ReflectionParameter;
 use ReflectionProperty;
-use TheCodingMachine\GraphQLite\Annotations\AbstractRequest;
+use TheCodingMachine\GraphQLite\Annotations\AbstractGraphQLElement;
 use TheCodingMachine\GraphQLite\Annotations\Decorate;
+use TheCodingMachine\GraphQLite\Annotations\EnumValue;
 use TheCodingMachine\GraphQLite\Annotations\Exceptions\ClassNotFoundException;
 use TheCodingMachine\GraphQLite\Annotations\Exceptions\InvalidParameterException;
 use TheCodingMachine\GraphQLite\Annotations\ExtendType;
@@ -195,11 +197,29 @@ public function getExtendTypeAnnotation(ReflectionClass $refClass): ExtendType|n
         return $extendType;
     }
 
-    /** @param class-string<AbstractRequest> $annotationClass */
-    public function getRequestAnnotation(ReflectionMethod $refMethod, string $annotationClass): AbstractRequest|null
+    /**
+     * Returns the {@see EnumValue} attribute declared on a PHP enum case, or null when no
+     * attribute is present. Callers use this to resolve the explicit description and deprecation
+     * reason before falling back to docblock parsing.
+     */
+    public function getEnumValueAnnotation(ReflectionEnumUnitCase $refCase): EnumValue|null
+    {
+        $attribute = $refCase->getAttributes(EnumValue::class)[0] ?? null;
+        if ($attribute === null) {
+            return null;
+        }
+
+        $instance = $attribute->newInstance();
+        assert($instance instanceof EnumValue);
+
+        return $instance;
+    }
+
+    /** @param class-string<AbstractGraphQLElement> $annotationClass */
+    public function getGraphQLElementAnnotation(ReflectionMethod $refMethod, string $annotationClass): AbstractGraphQLElement|null
     {
         $queryAnnotation = $this->getMethodAnnotation($refMethod, $annotationClass);
-        assert($queryAnnotation instanceof AbstractRequest || $queryAnnotation === null);
+        assert($queryAnnotation instanceof AbstractGraphQLElement || $queryAnnotation === null);
 
         return $queryAnnotation;
     }

src/Annotations/AbstractGraphQLElement.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Annotations;
+
+/**
+ * Shared base for every attribute that declares an invokable GraphQL schema element with a
+ * return type — {@see Query}, {@see Mutation}, {@see Subscription}, and {@see Field}. Each of
+ * those attributes inherits a GraphQL-level name, an explicit return type override, and a
+ * schema description from this class.
+ */
+abstract class AbstractGraphQLElement
+{
+    private string|null $outputType;
+
+    private string|null $name;
+
+    private string|null $description;
+
+    /** @param mixed[] $attributes */
+    public function __construct(
+        array $attributes = [],
+        string|null $name = null,
+        string|null $outputType = null,
+        string|null $description = null,
+    ) {
+        $this->outputType  = $outputType ?? $attributes['outputType'] ?? null;
+        $this->name        = $name ?? $attributes['name'] ?? null;
+        $this->description = $description ?? $attributes['description'] ?? null;
+    }
+
+    /**
+     * Returns the GraphQL return type for this schema element (as a string).
+     * The string can represent the FQCN of the type or an entry in the container resolving to the GraphQL type.
+     */
+    public function getOutputType(): string|null
+    {
+        return $this->outputType;
+    }
+
+    /**
+     * Returns the GraphQL name of the query/mutation/subscription/field.
+     * If not specified, the name of the PHP method is used instead.
+     */
+    public function getName(): string|null
+    {
+        return $this->name;
+    }
+
+    /**
+     * Returns the explicit description for this schema element, or null if none was provided.
+     *
+     * A null return means "no explicit description" and the schema builder may fall back to the
+     * docblock summary (if docblock descriptions are enabled on the SchemaFactory). An explicit
+     * empty string blocks the docblock fallback and produces an empty description.
+     */
+    public function getDescription(): string|null
+    {
+        return $this->description;
+    }
+}

src/Annotations/AbstractRequest.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Annotations;
+
+use Attribute;
+
+/**
+ * Attaches GraphQL metadata to an individual enum case.
+ *
+ * Applied to cases of a PHP 8.1+ native enum exposed as a GraphQL enum type, this attribute
+ * provides the schema description and deprecation reason for that value without relying on
+ * docblock parsing — mirroring the explicit {@see Type::$description} and
+ * {@see Field::$description} pattern that the rest of the attribute system uses.
+ *
+ * The attribute is named after the GraphQL specification's term for an enum member ("enum
+ * value", see §3.5.2 of the spec and the `__EnumValue` introspection type), which matches the
+ * GraphQL-spec-mirroring naming convention of every other graphqlite attribute (`#[Type]`,
+ * `#[Field]`, `#[Query]`, etc.). The underlying PHP language construct is `case`; the GraphQL
+ * schema element it produces is an enum value.
+ *
+ * Example:
+ * ```php
+ * #[Type]
+ * enum Genre: string
+ * {
+ *     #[EnumValue(description: 'Fiction works including novels and short stories.')]
+ *     case Fiction = 'fiction';
+ *
+ *     #[EnumValue(deprecationReason: 'Use NonFiction::Essay instead.')]
+ *     case Essay = 'essay';
+ *
+ *     case Poetry = 'poetry'; // no explicit metadata — falls back to docblock
+ * }
+ * ```
+ *
+ * Precedence rules match the rest of the description system: an explicit `description` wins
+ * over any docblock summary on the case; an explicit `deprecationReason` wins over any
+ * `@deprecated` tag in the case docblock. Passing an empty-string description deliberately
+ * publishes an empty description and suppresses the docblock fallback at that site (see the
+ * {@see \TheCodingMachine\GraphQLite\Utils\DescriptionResolver} for details).
+ */
+#[Attribute(Attribute::TARGET_CLASS_CONSTANT)]
+final class EnumValue
+{
+    public function __construct(
+        public readonly string|null $description = null,
+        public readonly string|null $deprecationReason = null,
+    ) {
+    }
+}

src/Annotations/EnumValue.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Annotations\Exceptions;
+
+use BadMethodCallException;
+
+use function implode;
+
+/**
+ * Thrown when both a #[Type] attribute and one or more #[ExtendType] attributes (or multiple
+ * #[ExtendType] attributes alone) declare a `description` for the same GraphQL type.
+ *
+ * A GraphQL type has exactly one description, so GraphQLite must be able to pick a single
+ * canonical source. Rather than silently resolving the conflict via declaration order, the
+ * schema builder rejects the ambiguity with a clear error listing every offending source.
+ *
+ * Descriptions may therefore live on the base #[Type] OR on exactly one #[ExtendType], never
+ * on both, and never on more than one #[ExtendType] for the same target class.
+ */
+class DuplicateDescriptionOnTypeException extends BadMethodCallException
+{
+    /**
+     * @param class-string<object> $targetClass
+     * @param list<string>         $sources    Human-readable descriptions of the attribute sources
+     *                                         that contributed a description (e.g. class names).
+     */
+    public static function forType(string $targetClass, array $sources): self
+    {
+        return new self(
+            'A GraphQL type may only have a description declared on the #[Type] attribute OR on exactly one #[ExtendType] attribute, never more than one. '
+            . 'Target type class "' . $targetClass . '" received descriptions from multiple sources: '
+            . implode(', ', $sources) . '. '
+            . 'Keep the description on the #[Type] attribute, or move it to at most one #[ExtendType] attribute.',
+        );
+    }
+}

src/Annotations/Exceptions/DuplicateDescriptionOnTypeException.php

@@ -21,12 +21,14 @@ class ExtendType
     /** @var class-string<object>|null */
     private string|null $class;
     private string|null $name;
+    private string|null $description;
 
     /** @param mixed[] $attributes */
     public function __construct(
         array $attributes = [],
         string|null $class = null,
         string|null $name = null,
+        string|null $description = null,
     ) {
         $className = isset($attributes['class']) ? ltrim($attributes['class'], '\\') : null;
         $className = $className ?? $class;
@@ -35,6 +37,7 @@ public function __construct(
         }
         $this->name = $name ?? $attributes['name'] ?? null;
         $this->class = $className;
+        $this->description = $description ?? $attributes['description'] ?? null;
         if (! $this->class && ! $this->name) {
             throw new BadMethodCallException('In attribute #[ExtendType], missing one of the compulsory parameter "class" or "name".');
         }
@@ -55,4 +58,17 @@ public function getName(): string|null
     {
         return $this->name;
     }
+
+    /**
+     * Returns the explicit description contributed by this type extension, or null if none was provided.
+     *
+     * A GraphQL type carries exactly one description. If both the base #[Type] and this #[ExtendType]
+     * (or multiple #[ExtendType] attributes targeting the same class) provide a description, the
+     * schema builder throws DuplicateDescriptionOnTypeException. Descriptions may therefore live on
+     * #[Type] OR on at most one #[ExtendType], never on both.
+     */
+    public function getDescription(): string|null
+    {
+        return $this->description;
+    }
 }

src/Annotations/ExtendType.php

@@ -15,13 +15,19 @@ class Factory
 {
     private string|null $name;
     private bool $default;
+    private string|null $description;
 
     /** @param mixed[] $attributes */
-    public function __construct(array $attributes = [], string|null $name = null, bool|null $default = null)
-    {
+    public function __construct(
+        array $attributes = [],
+        string|null $name = null,
+        bool|null $default = null,
+        string|null $description = null,
+    ) {
         $this->name = $name ?? $attributes['name'] ?? null;
         // This IS the default if no name is set and no "default" attribute is passed.
         $this->default = $default ?? $attributes['default'] ?? ! isset($attributes['name']);
+        $this->description = $description ?? $attributes['description'] ?? null;
 
         if ($this->name === null && $this->default === false) {
             throw new GraphQLRuntimeException('A #[Factory] that has "default=false" attribute must be given a name (i.e. add a name="FooBarInput" attribute).');
@@ -44,4 +50,17 @@ public function isDefault(): bool
     {
         return $this->default;
     }
+
+    /**
+     * Returns the explicit description for the GraphQL input type produced by this factory,
+     * or null if none was provided.
+     *
+     * A null return means "no explicit description" and the schema builder may fall back to the
+     * docblock summary (if docblock descriptions are enabled on the SchemaFactory). An explicit
+     * empty string blocks the docblock fallback and produces an empty description.
+     */
+    public function getDescription(): string|null
+    {
+        return $this->description;
+    }
 }

src/Annotations/Factory.php

@@ -11,7 +11,7 @@
 use const E_USER_DEPRECATED;
 
 #[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
-class Field extends AbstractRequest
+class Field extends AbstractGraphQLElement
 {
     private string|null $prefetchMethod;
 

src/Annotations/Field.php

@@ -7,6 +7,6 @@
 use Attribute;
 
 #[Attribute(Attribute::TARGET_METHOD)]
-class Mutation extends AbstractRequest
+class Mutation extends AbstractGraphQLElement
 {
 }

src/Annotations/Mutation.php

@@ -7,6 +7,6 @@
 use Attribute;
 
 #[Attribute(Attribute::TARGET_METHOD)]
-class Query extends AbstractRequest
+class Query extends AbstractGraphQLElement
 {
 }