Improve directive descriptions and sync docs with code by spawnia · Pull Request #2812 · nuwave/lighthouse

spawnia · 2026-10-25T15:51:20Z

Directive descriptions were hard-wrapped mid-sentence, which contradicts the Semantic Line Breaks rule in AGENTS.md.
This puts every sentence on its own line, in src/ and in the mirrored definitions in docs/master/.
PHPDoc and Markdown also get one sentence per line.

It also rewords unclear or run-on descriptions, except the Federation directives, which stay close to the Apollo docs.
For example, edgeType no longer refers to an Edge interface that Lighthouse does not have.

Directive definitions in docs/master/ now match src/.
Before, the docs lacked locations of @feature, @hide and @show, the repeatable of @feature, and gave returnValue of the @can* directives the wrong type.

The docs now show the @mock definition.
They also say which directives the default field_middleware setting applies to every field.

Filler words such as "easily", "simply" and "just" are removed from src/ and docs/master/.

Changelog

Changed

Improve wording of directive descriptions

Fixed

Fix directive definitions in docs that differ from the code

🤖 Generated with Claude Code

Copilot

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

2 open issues

The PR description explicitly says code examples/fenced blocks are untouched, but this file shows… · New
The PR description explicitly says code examples/fenced blocks are untouched, but this file shows… · New

What changed in this PR

Reformats GraphQL directive descriptions to follow Semantic Line Breaks (one sentence per line) across src/ and the mirrored snippets in docs/master/.

Changes:

Reflow directive description strings in src/ to avoid mid-sentence hard wraps.
Apply the same sentence-per-line formatting to mirrored directive definitions in docs/master/.
Some fenced PHP code examples in docs/master/api-reference/directives.md were also reflowed.

File	Description
src/WhereConditions/WhereHasConditionsDirective.php	Reflows directive description to a single sentence per line.
src/Validation/ValidatorDirective.php	Splits multi-sentence description into separate lines.
src/Validation/RulesForArrayDirective.php	Reflows description text to avoid mid-sentence wrapping.
src/Validation/RulesDirective.php	Reflows description text to avoid mid-sentence wrapping.
src/Tracing/TracingDirective.php	Reflows description text to a single line for the sentence.
src/Subscriptions/Directives/BroadcastDirective.php	Reflows description text to avoid mid-sentence wrapping.
src/SoftDeletes/SoftDeletesDirective.php	Reflows description text to avoid mid-sentence wrapping.
src/Schema/Directives/WithDirective.php	Reflows argument description text.
src/Schema/Directives/WithCountDirective.php	Splits multi-sentence note into separate lines.
src/Schema/Directives/WhereNotBetweenDirective.php	Reflows description text to a single sentence line.
src/Schema/Directives/WhereBetweenDirective.php	Reflows description text to a single sentence line.
src/Schema/Directives/UpsertManyDirective.php	Reflows argument description text.
src/Schema/Directives/UpsertDirective.php	Reflows argument description text.
src/Schema/Directives/UploadDirective.php	Reflows description text to a single sentence line.
src/Schema/Directives/UpdateManyDirective.php	Reflows argument description text.
src/Schema/Directives/UpdateDirective.php	Reflows argument description text.
src/Schema/Directives/ThrottleDirective.php	Splits two sentences onto separate lines.
src/Schema/Directives/SpreadDirective.php	Reflows description text to a single sentence line.
src/Schema/Directives/NestDirective.php	Reflows description text to a single sentence line.
src/Schema/Directives/MorphToManyDirective.php	Reflows argument descriptions to sentence-per-line.
src/Schema/Directives/MorphToDirective.php	Reflows argument description to sentence-per-line.
src/Schema/Directives/MorphOneDirective.php	Reflows argument description to sentence-per-line.
src/Schema/Directives/MorphManyDirective.php	Reflows argument descriptions to sentence-per-line.
src/Schema/Directives/MethodDirective.php	Reflows description text to avoid mid-sentence wrapping.
src/Schema/Directives/LimitDirective.php	Splits multi-sentence paragraphs into separate lines.
src/Schema/Directives/LikeDirective.php	Reflows argument description to a single sentence line.
src/Schema/Directives/LazyLoadDirective.php	Reflows description text to a single sentence line.
src/Schema/Directives/InjectDirective.php	Splits multi-sentence argument docs into separate lines.
src/Schema/Directives/HasOneThroughDirective.php	Reflows argument description to sentence-per-line.
src/Schema/Directives/HasOneDirective.php	Reflows argument description to sentence-per-line.
src/Schema/Directives/HasManyThroughDirective.php	Reflows argument descriptions to sentence-per-line.
src/Schema/Directives/HasManyDirective.php	Reflows argument descriptions to sentence-per-line.
src/Schema/Directives/EnumDirective.php	Reflows description text to avoid mid-sentence wrapping.
src/Schema/Directives/DeleteDirective.php	Reflows argument description text.
src/Schema/Directives/CreateManyDirective.php	Reflows argument description text.
src/Schema/Directives/CreateDirective.php	Reflows argument description text.
src/Schema/Directives/BelongsToManyDirective.php	Reflows argument descriptions to sentence-per-line.
src/Schema/Directives/BelongsToDirective.php	Reflows argument description to sentence-per-line.
src/GlobalId/NodeDirective.php	Reflows description text to a single sentence line.
src/GlobalId/GlobalIdDirective.php	Reflows semicolon-separated sentence to a single line.
src/Federation/Directives/TagDirective.php	Splits multi-sentence description into separate lines.
src/Federation/Directives/ShareableDirective.php	Reflows description paragraphs to sentence-per-line.
src/Federation/Directives/RequiresDirective.php	Splits multi-sentence description into separate lines.
src/Federation/Directives/ProvidesDirective.php	Splits multi-sentence description into separate lines.
src/Federation/Directives/OverrideDirective.php	Splits multi-sentence description into separate lines.
src/Federation/Directives/KeyDirective.php	Reflows description text to a single sentence line.
src/Federation/Directives/InterfaceObjectDirective.php	Reflows description text to a single sentence line.
src/Federation/Directives/InaccessibleDirective.php	Reflows description paragraphs to sentence-per-line.
src/Federation/Directives/ExternalDirective.php	Splits multi-sentence description into separate lines.
src/Federation/Directives/ExtendsDirective.php	Splits multi-sentence description into separate lines.
src/Federation/Directives/ComposeDirectiveDirective.php	Reflows description text to a single sentence line.
src/Defer/DeferrableDirective.php	Reflows description text to a single sentence line.
src/Cache/CacheDirective.php	Reflows description text to avoid mid-sentence wrapping.
src/Auth/GuardDirective.php	Reflows description text to a single sentence line.
src/Auth/CanQueryDirective.php	Reflows description text to a single sentence line.
src/Auth/CanDirective.php	Reflows multiple description blocks to sentence-per-line.
src/Auth/BaseCanDirective.php	Reflows shared argument description to sentence-per-line.
src/Async/AsyncDirective.php	Reflows multi-sentence paragraph to sentence-per-line.
docs/master/eloquent/complex-where-conditions.md	Mirrors the `@whereHasConditions` description reflow.
docs/master/digging-deeper/client-directives.md	Reflows directive argument description to a single sentence line.
docs/master/api-reference/directives.md	Mirrors description reflow; also reflows some fenced PHP code examples.

_{Review effort: Lite}

The formatter paired `"""` across markdown fences, which reflowed PHP examples and skipped the descriptions in between. 🤖 Generated with Claude Code

🤖 Generated with Claude Code

…ld by default 🤖 Generated with Claude Code

🤖 Generated with Claude Code

The docs held outdated copies with hard-wrapped comments. 🤖 Generated with Claude Code

🤖 Generated with Claude Code

…-sembr # Conflicts: # src/WhereConditions/SQLOperator.php

🤖 Generated with Claude Code

Copilot

🟢 Approval recommended

The changes preserve runtime logic, align documentation with existing behavior, and leave no unresolved review issues.

No open issues 🎉

2 resolved since last review

The PR description explicitly says code examples/fenced blocks are untouched, but this file shows…
The PR description explicitly says code examples/fenced blocks are untouched, but this file shows…

_{Review effort: Balanced}

spawnia and others added 2 commits October 25, 2026 16:51

Format directive descriptions with one sentence per line

c57fe1e

🤖 Generated with Claude Code

Prettify docs

b3aeaea

spawnia requested a balanced review from Copilot October 25, 2026 16:14

spawnia marked this pull request as ready for review October 25, 2026 16:14

Copilot AI reviewed Oct 25, 2026

View reviewed changes

Comment thread docs/master/api-reference/directives.md Outdated

Comment thread docs/master/api-reference/directives.md Outdated

Restore code blocks in directives docs and format missed descriptions

3be2241

The formatter paired `"""` across markdown fences, which reflowed PHP examples and skipped the descriptions in between. 🤖 Generated with Claude Code

Copilot stopped reviewing on behalf of spawnia due to an error October 25, 2026 16:36
The job was not acquired by a runner even after multiple attempts.

spawnia commented Oct 26, 2026

View reviewed changes

Comment thread docs/master/api-reference/directives.md Outdated

spawnia commented Oct 26, 2026

View reviewed changes

Comment thread docs/master/api-reference/directives.md Outdated

spawnia commented Oct 26, 2026

View reviewed changes

Comment thread docs/master/api-reference/directives.md Outdated

spawnia commented Oct 26, 2026

View reviewed changes

Comment thread docs/master/api-reference/directives.md Outdated

spawnia added 6 commits October 26, 2026 08:44

Split @async return type sentence

02f06e4

🤖 Generated with Claude Code

Clarify when to specify the relation argument

238c006

🤖 Generated with Claude Code

Clarify what the edgeType argument does

22a214a

🤖 Generated with Claude Code

Split @cache isPrivate description

94f9955

🤖 Generated with Claude Code

Improve wording of directive descriptions

4041b4e

🤖 Generated with Claude Code

Sync directive definitions between docs and code

a38be1b

🤖 Generated with Claude Code

spawnia changed the title ~~Format directive descriptions with one sentence per line~~ Improve directive descriptions and sync docs with code Oct 26, 2026

spawnia added 10 commits October 26, 2026 09:10

Describe and document @mock

dcafa49

🤖 Generated with Claude Code

Mention that global field middleware directives apply to every field

1c56b91

🤖 Generated with Claude Code

Remove filler words from prose

721ee68

🤖 Generated with Claude Code

Document that @Trim and @convertEmptyStringsToNull apply to every fie…

c2216a7

…ld by default 🤖 Generated with Claude Code

Put one sentence per line in Markdown

c9a1bd3

🤖 Generated with Claude Code

Put one sentence per line in PHP comments

f2cb729

🤖 Generated with Claude Code

Copy event classes into the events docs from src

ea603dc

The docs held outdated copies with hard-wrapped comments. 🤖 Generated with Claude Code

Put one sentence per line in comments of docs code examples

19cdc09

🤖 Generated with Claude Code

Merge remote-tracking branch 'origin/master' into format-descriptions…

c8f927e

…-sembr # Conflicts: # src/WhereConditions/SQLOperator.php

Fix grammar of JSON length operator descriptions

85f6f2a

🤖 Generated with Claude Code

spawnia commented Oct 26, 2026

View reviewed changes

Comment thread docs/master/api-reference/events.md Outdated

Comment thread docs/master/api-reference/resolvers.md Outdated

Comment thread docs/master/subscriptions/getting-started.md Outdated

Comment thread src/Bind/ModelBinding.php Outdated

Keep ManipulateResult description in one sentence

4e3928e

🤖 Generated with Claude Code

spawnia added 5 commits October 26, 2026 09:55

Split ResolveInfo description in resolvers docs

c911b64

🤖 Generated with Claude Code

Shorten subscription expiry sentence

d44b613

🤖 Generated with Claude Code

Shorten ModelBinding comment

d32f7fb

🤖 Generated with Claude Code

Remove superlative filler from docs

a2514c1

🤖 Generated with Claude Code

Split sentences over 150 characters

d24f923

🤖 Generated with Claude Code

spawnia requested a balanced review from Copilot October 26, 2026 09:59

Copilot started reviewing on behalf of spawnia October 26, 2026 10:00

View session

Copilot AI reviewed Oct 26, 2026

View reviewed changes

Navigation Menu

Repository navigation

Improve directive descriptions and sync docs with code - #2812

Improve directive descriptions and sync docs with code#2812
spawnia wants to merge 25 commits into
masterfrom
format-descriptions-sembr

spawnia commented Oct 25, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

spawnia commented Oct 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog

Changed

Fixed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

spawnia commented Oct 25, 2026 •

edited

Loading