Improve directive descriptions and sync docs with code

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,7 +15,5 @@ If so, describe the necessary changes in UPGRADE.md. -->
 ## Changelog
 
 <!-- Do not edit CHANGELOG.md.
-Write entries as they should appear there,
-grouped under Added, Changed, Deprecated,
-Removed, Fixed or Security.
+Write entries as they should appear there, grouped under Added, Changed, Deprecated, Removed, Fixed or Security.
 Write "None" if users do not notice the change. -->

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Lighthouse Contribution Guide
 
 Thank you for contributing to Lighthouse.
-Here are some tips and guidelines to make this easy for you.
+Here are some tips and guidelines to help you.
 
 ## Open a Pull Request
 
@@ -26,9 +26,9 @@ Before you release a new version, make sure to familiarize yourself with:
 
 To create a new release, follow these steps:
 1. Copy the `## Changelog` sections of the pull requests merged since the last release into [`CHANGELOG.md`](CHANGELOG.md), appending each pull request URL.
-Add missing entries if needed.
+   Add missing entries if needed.
 2. Based on those entries and the previous version, define the next version number.
-Add it to [`CHANGELOG.md`](CHANGELOG.md).
+   Add it to [`CHANGELOG.md`](CHANGELOG.md).
 3. [Draft a new release](https://github.com/nuwave/lighthouse/releases/new)
 4. Add the version number as both tag and title
 5. Add the changelog entries as the description

UPGRADE.md

@@ -14,9 +14,9 @@ Compare your `lighthouse.php` against the latest [default configuration](src/lig
 Methods you need to explicitly call to set up test traits were removed in favor of automatic setup.
 
 - Remove calls to `Nuwave\Lighthouse\Testing\RefreshesSchemaCache::bootRefreshesSchemaCache()`.
-This only works when your test class uses the trait `Nuwave\Lighthouse\Testing\MakesGraphQLRequests`.
+  This only works when your test class uses the trait `Nuwave\Lighthouse\Testing\MakesGraphQLRequests`.
 - Replace calls to `Nuwave\Lighthouse\Testing\MakesGraphQLRequests::setUpSubscriptionEnvironment()` with ` use Nuwave\Lighthouse\Testing\TestsSubscriptions`.
-This only works when your test class extends `Illuminate\Foundation\Testing\TestCase`.
+  This only works when your test class extends `Illuminate\Foundation\Testing\TestCase`.
 
 ### `EnsureXHR` is enabled in the default configuration
 
@@ -240,7 +240,7 @@ final class MyDirective extends BaseDirective implements FieldResolver
 
 ### Simplify wrapping resolvers in `FieldMiddleware` directives
 
-Wrapping resolvers is very common in `FieldMiddleware` directives and is now simplified.
+Wrapping resolvers is common in `FieldMiddleware` directives and is now simplified.
 
 ```diff
 use Nuwave\Lighthouse\Execution\ResolveInfo;
@@ -306,7 +306,8 @@ Use `executeQueryString()` for executing a string query or `executeParsedQuery()
 See https://github.com/webonyx/graphql-php/blob/master/UPGRADE.md#breaking-removed-error-extension-field-category.
 
 You can [leverage `GraphQL\Error\ProvidesExtensions`](https://lighthouse-php.com/master/digging-deeper/error-handling.html#additional-error-information) to restore `category` in your custom exceptions.
-Additionally, you may [implement a custom error handler](https://lighthouse-php.com/master/digging-deeper/error-handling.html#registering-error-handlers) that wraps well-known third-party exceptions with your own exception that adds an appropriate `category`.
+Additionally, you may [implement a custom error handler](https://lighthouse-php.com/master/digging-deeper/error-handling.html#registering-error-handlers) that wraps well-known third-party exceptions with your own exception.
+Your exception adds an appropriate `category`.
 
 ### Use native interface for errors with extensions
 
@@ -359,7 +360,8 @@ If you had previously depended on the presence of the schema in your cache, then
 
 ### Register `ScoutServiceProvider` if you use `@search`
 
-If you use the `@search` directive in your schema, you will now need to register the service provider `Nuwave\Lighthouse\Scout\ScoutServiceProvider`, it is no longer registered by default.
+If you use the `@search` directive in your schema, register the service provider `Nuwave\Lighthouse\Scout\ScoutServiceProvider`.
+It is no longer registered by default.
 See [registering providers in Laravel](https://laravel.com/docs/providers#registering-providers).
 
 ### Update `lighthouse.guard` configuration
@@ -402,8 +404,7 @@ The recommended process for finding breaking changes is:
 
 1. Print your schema before upgrading: `php artisan lighthouse:print-schema > old.graphql`
 1. Upgrade, then re-print your schema: `php artisan lighthouse:print-schema > new.graphql`
-1. Use [graphql-inspector](https://github.com/kamilkisiela/graphql-inspector) to compare your
-changes: `graphql-inspector diff old.graphql new.graphql`
+1. Use [graphql-inspector](https://github.com/kamilkisiela/graphql-inspector) to compare your changes: `graphql-inspector diff old.graphql new.graphql`
 
 ### Rename `resolve` to `__invoke`
 
@@ -432,13 +433,14 @@ type Query {
 }
 ```
 
-Note that [@guard](docs/master/api-reference/directives.md#guard) does not log in users.
-To ensure the user is logged in, add the `AttemptAuthenticate` middleware to your `lighthouse.php` middleware config, see the [default config](src/lighthouse.php) for an example.
+[@guard](docs/master/api-reference/directives.md#guard) does not log in users.
+To ensure the user is logged in, add the `AttemptAuthenticate` middleware to your `lighthouse.php` middleware config.
+See the [default config](src/lighthouse.php) for an example.
 
 If you used `@middleware` for authorization, replace it with [@can](docs/master/api-reference/directives.md#can).
 
 Other functionality can be replaced by a custom [`FieldMiddleware`](docs/master/custom-directives/field-directives.md#fieldmiddleware) directive.
-Just like Laravel Middleware, it can wrap around individual field resolvers.
+Like Laravel Middleware, it can wrap around individual field resolvers.
 
 ### Directives must have an SDL definition
 
@@ -452,7 +454,7 @@ If you previously implemented `DefinedDirective`, remove it from your directives
 +class TrimDirective extends BaseDirective implements ArgTransformerDirective
 ```
 
-Instead of just providing the name of the directive, all directives must now return an SDL definition that formally describes them.
+Instead of only providing the name of the directive, all directives must now return an SDL definition that formally describes them.
 
 ```diff
 -    public function name()
@@ -503,7 +505,8 @@ Client queries will have to be changed like this:
 }
 ```
 
-If you absolutely cannot break your clients, you can re-implement `@orderBy` in your project. It is a relatively simple `ArgManipulator` directive.
+If you absolutely cannot break your clients, you can re-implement `@orderBy` in your project.
+It is a small `ArgManipulator` directive.
 
 ### `@modelClass` and `@model` changed
 
@@ -545,9 +548,9 @@ type Mutation {
 }
 ```
 
-### `@method` passes down just ordered arguments
+### `@method` passes down only ordered arguments
 
-Instead of passing down the usual resolver arguments, the `@method` directive will now pass just the arguments given to a field.
+Instead of passing down the usual resolver arguments, the `@method` directive will now pass only the arguments given to a field.
 This behavior could previously be enabled through the `passOrdered` option, which is now removed.
 
 ```graphql
@@ -571,7 +574,8 @@ This affects custom directives that implemented one of the following interfaces:
 - `Nuwave\Lighthouse\Support\Contracts\ArgTransformerDirective`
 - `Nuwave\Lighthouse\Support\Contracts\ArgBuilderDirective`
 
-Whereas those interfaces previously extended `Nuwave\Lighthouse\Support\Contracts\ArgDirective`, you now have to choose if you want them to apply to entire lists of arguments, elements within that list.
+Those interfaces previously extended `Nuwave\Lighthouse\Support\Contracts\ArgDirective`.
+Now you have to choose if you want them to apply to entire lists of arguments, or to elements within that list.
 Or both.
 Change them as follows to make them behave like in v4:
 
@@ -589,10 +593,10 @@ use Nuwave\Lighthouse\Support\Contracts\DefinedDirective;
 The application of directives that implement the `ArgDirective` interface is split into three distinct phases:
 
 - Sanitize: Clean the input, e.g. trim whitespace.
-Directives can hook into this phase by implementing `ArgSanitizerDirective`.
+  Directives can hook into this phase by implementing `ArgSanitizerDirective`.
 - Validate: Ensure the input conforms to the expectations, e.g. check a valid email is given
 - Transform: Change the input before processing it further, e.g. hashing passwords.
-Directives can hook into this phase by implementing `ArgTransformerDirective`
+  Directives can hook into this phase by implementing `ArgTransformerDirective`
 
 ### Replace custom validation directives with validator classes
 
@@ -642,13 +646,16 @@ type Mutation {
 The event is no longer fired, and the event class was removed.
 Lighthouse now uses a queued job instead.
 
-If you manually fired the event, replace it by queuing a `Nuwave\Lighthouse\Subscriptions\BroadcastSubscriptionJob` or a call to `Nuwave\Lighthouse\Subscriptions\Contracts\BroadcastsSubscriptions::queueBroadcast()`.
+If you manually fired the event, queue a `Nuwave\Lighthouse\Subscriptions\BroadcastSubscriptionJob` instead.
+Alternatively, call `Nuwave\Lighthouse\Subscriptions\Contracts\BroadcastsSubscriptions::queueBroadcast()`.
 
-In case you depend on an event being fired whenever a subscription is queued, you can bind your own implementation of `Nuwave\Lighthouse\Subscriptions\Contracts\BroadcastsSubscriptions`.
+You may depend on an event being fired whenever a subscription is queued.
+Then bind your own implementation of `Nuwave\Lighthouse\Subscriptions\Contracts\BroadcastsSubscriptions`.
 
 ### `TypeRegistry` does not register duplicates by default
 
-Calling `register()` on the `Nuwave\Lighthouse\Schema\TypeRegistry` now throws when passing a type that was already registered, as this most likely is an error.
+Calling `register()` on the `Nuwave\Lighthouse\Schema\TypeRegistry` now throws when passing a type that was already registered.
+This is most likely an error.
 
 If you want to previous behavior of overwriting existing types, use `overwrite()` instead.
 
@@ -662,7 +669,7 @@ $typeRegistry = app(\Nuwave\Lighthouse\Schema\TypeRegistry::class);
 
 Since GraphQL constrains allowed inputs by design, mass assignment protection is not needed.
 By default, Lighthouse will use `forceFill()` when populating a model with arguments in mutation directives.
-This allows you to use mass assignment protection for other cases where it is actually useful.
+This allows you to use mass assignment protection for other cases where it is useful.
 
 If you need to revert to the old behavior of using `fill()`, you can change your `lighthouse.php`:
 

docs/master/api-reference/commands.md

@@ -61,7 +61,8 @@ A great way to keep up to date with your current version of Lighthouse is to add
     ],
 ```
 
-If the generated definitions conflict with those provided by your IDE, try `--omit-built-in` to avoid redefining built-in directives such as `@deprecated`.
+If the generated definitions conflict with those of your IDE, try `--omit-built-in`.
+It avoids redefining built-in directives such as `@deprecated`.
 
 ## interface
 
@@ -89,7 +90,7 @@ Compile the GraphQL schema and print the result.
 php artisan lighthouse:print-schema
 ```
 
-This can be quite useful, as the root `.graphql` files do not necessarily contain the whole schema.
+This is useful, as the root `.graphql` files do not necessarily contain the whole schema.
 Schema imports, native PHP types and schema manipulation may influence the final schema.
 
 Use the `-W` / `--write` option to output the schema to default file storage (usually `storage/app`).