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

[oojacoboo]

Closes #453 and #740.

Problem

GraphQLite implicitly pulls the PHP docblock summary of every schema-defining annotation into the GraphQL schema as the element's description, with no way to opt out. This creates two problems:

1. Silent schema leakage. Dev-facing docblocks (implementation notes, @see references, @deprecated reminders, TODO comments) ship verbatim to public API consumers. The security motivation is summarized in comment on Graphql enum description #740:

   Defaulting to phpdoc is a potential security issue with unintended consequences. And, IMO, should be disabled by default. It was a bad design choice.

2. Inconsistent attribute API. #[Field], #[Input], #[MagicField], #[SourceField] already accept an explicit description argument. #[Query], #[Mutation], #[Subscription], #[Type], #[ExtendType], #[Factory] do not — the escape hatch is missing exactly where schemas need it most. Individual enum cases also have no attribute-level metadata.

Fix

1. description argument on every schema-defining attribute

AbstractGraphQLElement (formerly AbstractRequest, see renames below) gains a trailing optional ?string $description parameter, automatically adding the argument to #[Query], #[Mutation], #[Subscription], and #[Field]. #[Type], #[ExtendType], and #[Factory] each get the same parameter directly. The $attributes['description'] backfill mirrors the existing pattern on Field / Input / SourceField.

2. #[EnumValue] attribute for enum case metadata

New attribute targeting Attribute::TARGET_CLASS_CONSTANT carries an explicit description and deprecationReason for individual cases of a PHP 8.1+ native enum exposed as a GraphQL enum type:

#[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';

    case NonFiction = 'non-fiction'; // no attribute — description from docblock today, hidden after the future opt-in flip
}

The name mirrors the GraphQL spec's term ("enum values" per §3.5.2, __EnumValue in introspection, enumValues field) and webonyx/graphql-php's internal EnumValueDefinition. It matches graphqlite's existing GraphQL-spec-mirroring convention (#[Type], #[Field], #[Query], …) rather than the PHP language term "case". AnnotationReader::getEnumValueAnnotation(ReflectionEnumUnitCase) reads the attribute and is threaded into EnumTypeMapper::mapByClassName().

3. Deprecation advisory for enums that have not adopted #[EnumValue]

When a #[Type]-mapped enum declares zero #[EnumValue] attributes across its cases, EnumTypeMapper emits a PHP E_USER_DEPRECATED notice. This preserves today's behaviour — every case is still automatically exposed — but announces a planned opt-in migration: a future major release will require at least one #[EnumValue]-annotated case per #[Type]-mapped enum, and only annotated cases will participate in the schema (mirroring #[Field]'s opt-in model on classes).

Partial annotation is intentional and silent. 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. Leaving some cases unannotated is the mechanism for hiding them from the public schema once the default flips — penalizing that pattern would defeat the whole point of selective exposure.

The practical benefit of the future opt-in model is selective exposure: an internal enum case can stay out of the public schema simply by omitting #[EnumValue], instead of forcing schema authors to split an enum or rename cases. After the flip, a resolver that returns an unannotated case triggers webonyx/graphql-php's standard enum serialization error (the value isn't in the enum type's values config) — the same spec-compliant behaviour that applies to any unknown enum value, and the mechanism that makes selective exposure safe.

Adopters who aren't ready to decide which cases to expose can silence the advisory with a bare #[EnumValue] on a single case (no description, no deprecation — just the acknowledgement). Matches graphqlite's existing deprecation pattern (e.g. addControllerNamespace, setGlobTTL).

4. SchemaFactory::setDocblockDescriptionsEnabled(bool $enabled)

New opt-out toggle, default true for backwards compatibility. Matches the existing set* setter pattern in SchemaFactory (setAuthenticationService, setNamingStrategy, setGlobTTL, …). When disabled, only explicit description arguments populate the schema.

5. Utils\DescriptionResolver

Tiny single-responsibility helper that encodes the precedence rule consistently across every extraction site. Constructor takes the toggle; resolve(?string $explicit, ?string $docblockDerived) applies the rule:

1. Explicit description: '…' wins.
2. Explicit description: '' (empty string) also wins — deliberately publishes an empty description and blocks the docblock fallback at that site.
3. Docblock-derived value — only when the toggle is enabled.
4. Otherwise null.

SchemaFactory::createSchema() constructs one resolver instance and threads it through FieldsBuilder, TypeGenerator, InputTypeGenerator, EnumTypeMapper, and TypeHandler. This fixes InputTypeGenerator::mapFactoryMethod() along the way — the long-standing // TODO: add comment argument. goes away and factory-produced input types now participate in description resolution.

6. #[ExtendType] description uniqueness

A GraphQL type has exactly one description. When both #[Type] and #[ExtendType] (or multiple #[ExtendType]s on the same class) declare a description, TypeGenerator throws DuplicateDescriptionOnTypeException at schema-build time, naming every offending source. Consumer code declaring a description on #[ExtendType] for a base #[Type] that did not provide one is the legitimate use case and is explicitly supported (e.g. an application describing a third-party library type). See the new Descriptions doc page for the full decision table.

Why this approach vs. a DescriptionFieldMiddleware?

The alternative middleware-based approach suggested on #453 was briefly considered but has two blocking gaps:

1. Factories aren't covered. @withinboredom's own middleware sketch on InputTypeGenerator::mapFactoryMethod doesn't call field middleware. #439 notes: "However, in factories, it doesn't work because the field middleware doesn't appear to be called at all for the generated fields."
2. Types aren't covered. TypeGenerator, InputTypeGenerator, and EnumTypeMapper construct types outside the field-middleware pipeline; there's nowhere for the middleware to intercept.

Only a first-class attribute argument + resolver pipeline can give the uniform coverage described in #740 ("All attributes that define a schema definition element should include a description argument.").

Breaking changes

Two internal renames bundled into the same PR for consistency with the new description terminology. Neither is used in userland application code, but custom middlewares or extensions may need updating.

1. QueryFieldDescriptor / InputFieldDescriptor: $comment constructor parameter and property renamed to $description. getComment() → getDescription(), withComment() → withDescription(), withAddedCommentLines() → withAddedDescriptionLines(). The GraphQL spec uses "description" everywhere (§2.5, introspection, webonyx config key); the old comment terminology was the odd one out.
2. AbstractRequest → AbstractGraphQLElement: the shared base for #[Query], #[Mutation], #[Subscription], and #[Field]. The new name accurately describes its role (it represents a GraphQL schema element with a return type and description), whereas "Request" collided with the more common HTTP meaning and misfit #[Field]. AnnotationReader::getRequestAnnotation() renamed to getGraphQLElementAnnotation() for symmetry.

An empty-string description: '' was previously indistinguishable from "no description provided" and fell through to the docblock. It now deliberately blocks the fallback and publishes an empty description. Users relying on the old behaviour should pass null (or simply omit the argument).

Deferred to follow-up PRs

Kept out of this PR to keep the scope reviewable:

• Flipping the enum-case opt-in default. A future major release will require at least one #[EnumValue]-annotated case per #[Type]-mapped enum and hide unannotated cases from the schema. This PR only emits the advisory deprecation notice; the default flip is a separate breaking change.
• Deprecated #[EnumType] annotation. Skipped in favour of the native PHP 8.1 enum + #[Type] / #[EnumValue] path, which is already covered by EnumTypeMapper.
• #[Decorate] description. The attribute wraps an existing input-type definition and has no obvious single description target; a follow-up with clear semantics is better than adding it here.
• Flipping setDocblockDescriptionsEnabled(false) as the default. A breaking change worth its own major-version release, per the security rationale on Graphql enum description #740.

Test plan

• New DescriptionResolverTest — 8-case precedence matrix (explicit non-empty, explicit empty, null + toggle on, null + toggle off, null + null, null + empty docblock, plus the constructor getter).
• New EnumValueTest — 5 unit cases (defaults / description only / deprecation only / both / empty-string description).
• New Integration/DescriptionTest — 15 end-to-end cases over a fresh SchemaFactory:
  • explicit description on #[Query], #[Mutation], #[Type], #[Field], native enum #[Type]
  • #[EnumValue] supplying case-level description
  • #[EnumValue] supplying case-level deprecation reason
  • enum case without #[EnumValue] falling back to docblock
  • deprecation advisory fires on an enum that declares zero #[EnumValue] attributes (via expectUserDeprecationMessageMatches)
  • advisory stays silent when an enum has partial #[EnumValue] annotation — locks in the "one acknowledgement silences the notice" contract
  • setDocblockDescriptionsEnabled(false) suppressing docblock-only enum cases while keeping #[EnumValue]-supplied descriptions
  • #[ExtendType(description: …)] supplying the description when the base #[Type] did not
  • docblock fallback still populating descriptions by default (BC)
  • setDocblockDescriptionsEnabled(false) suppressing every docblock path
  • duplicate descriptions across #[Type] + #[ExtendType] throwing DuplicateDescriptionOnTypeException with both sources named
• New unit tests per annotation (TypeTest, ExtendTypeTest, FactoryTest, QueryTest) confirming the description argument + getDescription() / $attributes['description'] paths.
• Existing 502 tests pass unchanged. Pre-existing enum fixtures (Color, Size, Position) gained a bare #[EnumValue] acknowledgement on one case each — documents the minimal upgrade path and keeps test output clean. Full suite is now 539 tests, 1244 assertions, green on PHP 8.2–8.5 via composer cs-check && composer phpstan && phpunit.

Documentation

• New page website/docs/descriptions.md (sidebar: Usage → Descriptions) covering the explicit argument, docblock fallback, precedence rule, SchemaFactory toggle, #[EnumValue] enum-case metadata, the planned enum-case opt-in migration with its advisory notice, and #[ExtendType] uniqueness rule.
• annotations-reference.md — each affected attribute's table row links to the new page; #[EnumValue] section added; cross-cutting concept pulled out of the reference list where it didn't belong.
• other-frameworks.mdx — setDocblockDescriptionsEnabled() added to the SchemaFactory setters example; short comment points to the new page.
• field-middlewares.md — descriptor method signatures updated.

Checklist

• Closes Add description attribute to annotations to override PHPDoc  #453
• Closes Graphql enum description #740 (both type-level and enum-case-level)
• composer cs-check clean
• composer phpstan clean
• vendor/bin/phpunit 539/539 green
• CI matrix — PHP 8.2 / 8.3 / 8.4 / 8.5 (will run on push)
• Docs updated
• Breaking changes called out in this PR body for the maintainer to lift into the GitHub release notes

[codecov-commenter]

Codecov Report

❌ Patch coverage is 97.97980% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.87%. Comparing base (53f9d49) to head (159f237).
⚠️ Report is 144 commits behind head on master.

Files with missing lines	Patch %	Lines
src/InputFieldDescriptor.php	50.00%	2 Missing ⚠️
src/Mappers/Parameters/TypeHandler.php	85.71%	1 Missing ⚠️
src/Mappers/Root/EnumTypeMapper.php	96.77%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #793      +/-   ##
============================================
- Coverage     95.72%   94.87%   -0.86%     
- Complexity     1773     1895     +122     
============================================
  Files           154      178      +24     
  Lines          4586     5010     +424     
============================================
+ Hits           4390     4753     +363     
- Misses          196      257      +61     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[oojacoboo]

For completeness, I've gone ahead and implemented a new #[EnumValue] attribute that supports description. This was the only remaining item not covered for descriptions and should fully solve #740.

It's worth pointing out here, that, in the future, #[EnumValue] attributes will be required for all cases/values that are to be exposed over the API. This follows the opt-in pattern for #[Field] and keeps a consistent mental model for defining a schema. Additionally, it allows for only exposing certain cases/values, where you may only want some for internal/backend support, but not publicly exposed in your graph. For now, a deprecation notice will be thrown to let developers know that this needs to be updated. In a future version, this will be flipped, and an error will be thrown for enums defined with a #[Type] attribute, but no #[EnumValue] attributes.