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.

Author: oojacoboo

src/AnnotationReader.php

@@ -8,7 +8,7 @@
 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\EnumType;
 use TheCodingMachine\GraphQLite\Annotations\Exceptions\ClassNotFoundException;
@@ -201,11 +201,11 @@ public function getEnumTypeAnnotation(ReflectionClass $refClass): EnumType|null
         return $this->getClassAnnotation($refClass, EnumType::class);
     }
 
-    /** @param class-string<AbstractRequest> $annotationClass */
-    public function getRequestAnnotation(ReflectionMethod $refMethod, string $annotationClass): AbstractRequest|null
+    /** @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,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
 {
 }

src/Annotations/Query.php

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