ALLI-21969: Clarify documentation

CHANGELOG.md

@@ -7,21 +7,21 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Fixed
 
-- `once` calls with no message handled will have an `{queueName} empty-receive`
+- `once` calls that handle no message will use an `{queueName} empty-receive`
   span name.
 
 ## 6.1.1
 
 ### Fixed
 
-- Fixed the open telemetry `_register.php` file autoload
+- Fixed autoloading for the OpenTelemetry `_register.php` file.
 
 ## 6.1.0
 
 ### Added
 
-- Added open telemetry instrumentation around `Consumer::once` and
-  `Driver::enqueue`. These respect [messaging span](https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/)
+- Added OpenTelemetry instrumentation around `Consumer::once` and
+  `Driver::enqueue`. These follow [messaging span](https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/)
   semantic conventions.
 
 ## 6.0.0
@@ -37,7 +37,7 @@ See [the upgrade guide](UPGRADE-6.0.md) for more information.
 
 ### Added
 
-- Support PHP `^7.4 || ^8.0`
+- Added support for PHP `^7.4 || ^8.0`
 
 ### Changed
 
@@ -49,26 +49,26 @@ See [the upgrade guide](UPGRADE-6.0.md) for more information.
 
 - PHP 7.3+ is required.
 - Implementing `PMG\Queue\Message` is no longer required! Messages passed
-  to the the producer and handled by the consumer can be any PHP object now.
-  In the cases where a plain object is used, the message *name* is the full
-  qualified class name. However, you may implement `Message` should you desire to
+  to the producer and handled by the consumer can now be any PHP object.
+  When a plain object is used, the message *name* is the fully qualified
+  class name. However, you may implement `Message` if you want to
   keep the old behavior of having a specific message name that differs from the
   FQCN.
 - `PMG\Queue\Router::queueFor` now typehints against `object` instead of
   `Message`.
 - All `PMG\Queue\MessageLifecycle` methods now typehint against `object`.
 - `PMG\Queue\Envelope` and `DefaultEnvelope` now deal with `object` messages
-  only and do not typehint again `Message`.
-- `PMG\Queue\Driver::enqueue` now typehints agains `object` instead of message.
-  if a driver gets an `Envelope` instance it should use that instead of creating
+  only and no longer typehint against `Message`.
+- `PMG\Queue\Driver::enqueue` now typehints against `object` instead of `Message`.
+  If a driver gets an `Envelope` instance, it should use that instead of creating
   its own envelope. See [`UPGRADE-5.0.md`](/UPGRADE-5.0.md) for more details.
 - `PMG\Queue\MessageHandler::handle` now typehints against `object` instead of
   `Message`.
 - `PMG\Queue\Producer::send` now typehints against `object` instead of `Message`.
-- `MessageLifecycle::failed` no longer has an `$isRetrying` argument, instead
-  `MessageLifecycyle::retrying` will be called instead.
+- `MessageLifecycle::failed` no longer has an `$isRetrying` argument. Instead,
+  `MessageLifecycle::retrying` will be called.
 - `PMG\Queue\Router::queueFor` now has a `?string` return type.
-- Drivers should no longer call `Envelope::retry` instead, instead consumers
+- Drivers should no longer call `Envelope::retry`. Instead, consumers
   should call this method along with any delay required from the `RetrySpec`.
   See `UPGRADE-5.0.md` for more details.
 
@@ -78,17 +78,17 @@ n/a
 
 ### Added
 
-- A new `MessageLifecycle::retrying` method was added that gets called whenever
+- A new `MessageLifecycle::retrying` method was added and is called whenever
   a message fails and is retrying.
 - `PMG\Queue\Lifecycle\DelegatingLifecycle` has a new named constructor:
   `fromIterable`. This uses PHP 7.1's `iterable` pseudo type.
-- `RetrySpec::retryDelay` method added to allow a message to be delayed when
-  retrying, if the driver supports it.
+- The `RetrySpec::retryDelay` method was added to allow a message to be delayed
+  when retrying, if the driver supports it.
 - `Envelope::retry` now accepts an `int $delay` to support delayed retries. Not all
-  drivers will be able to support delaying.
+  drivers will support delays.
 - Similarly, `PMG\Queue\Driver` implementations must no longer call
-  `Envelope::retry` as they were required to do previously. See `UPGRADE-5.0.md`
-  for more details. Instead `PMG\Queue\Consumer` implementations should call
+  `Envelope::retry`. See `UPGRADE-5.0.md` for more details. Instead,
+  `PMG\Queue\Consumer` implementations should call
   `Envelope::retry`.
 
 ### Removed
@@ -145,13 +145,13 @@ n/a
   to `ensureSerializer`.
 - [BC Break, Internals] `Driver` now has more strict type declarations.
 - [BC Break, Internals] `Driver::release` was introduced.
-- [BC Break, Internals] `Consumer::once` and `Consumer::run` Now take an optional
-  `MessageLifecycle` instance as their second argument. Only folks who wrote 
+- [BC Break, Internals] `Consumer::once` and `Consumer::run` now take an optional
+  `MessageLifecycle` instance as their second argument. Only people who wrote
   custom consumer implementations need to worry about this. See `DefaultConsumer`
-  for an example how this may be handled. End users can keep using the consumer
-  exactly as they were.
+  for an example of how this may be handled. End users can keep using the
+  consumer as before.
 - [BC Break, Internals] `MessageHandler::handle` now returns a promise object
-  from the `guzzlehttp/promises` library. Only folks who wrote custom handler
+  from the `guzzlehttp/promises` library. Only people who wrote custom handler
   implementations need to worry about this.
 - `RetrySpec::canRetry` now has a return type hint.
 - `Consumer::once` and `Consumer::run` have `string` typehints for their
@@ -182,10 +182,10 @@ n/a
 
 ### Added
 
-- Child processes that exit abnormaly in `PcntlForkingHandler` now throw an
-  `AbnormalExit` exception with some info about what went wrong. Practically
-  this has no impact: the job is still failed and (possibly) retried, but the
-  thrown exception will be logged and hopefully give users a better place to
+- Child processes that exit abnormally in `PcntlForkingHandler` now throw an
+  `AbnormalExit` exception with some information about what went wrong.
+  Practically, this has no impact: the job still fails and may be retried, but
+  the thrown exception will be logged to give users a better place to
   start debugging.
 
 
@@ -194,8 +194,8 @@ n/a
 ### Changed
 
 - `PcntlForkingHandler` now throws a `CouldNotFork` exception that causes the
-  consumer to exit unsuccessfully. Since a failure to fork is clearly on level
-  with a driver error -- a system issue, not an application issue -- this is
+  consumer to exit unsuccessfully. Since a failure to fork is on the same level
+  as a driver error, a system issue rather than an application issue, this is
   more in line with what *should* happen. The consumer will exit and its process
   manager can restart it.
 
@@ -205,7 +205,8 @@ n/a
 ### Added
 
 - There is a new `PMG\Queue\Handler\Pcntl` class that acts as a thin wrapper
-  around the `pcntl_*` functions and `exit`. Mostly done for testing purposes.
+  around the `pcntl_*` functions and `exit`. This exists mostly for testing
+  purposes.
 
 ## 3.0.0
 
@@ -214,16 +215,17 @@ n/a
 - [BC BREAK] PHP version requirement was bumped to 5.6
 - [BC BREAK] `DefaultConsumer::once` (and the `Consumer` interface) have been
   changed to make `once` safe to run in a loop. In other words, it never throws
-  exceptions unless it's a must stop or an exception thrown from a driver. All
-  other exceptions are logged, but not fatal. The idea here is to make consumers
+  exceptions unless it is a must-stop exception or an exception thrown from a
+  driver. All other exceptions are logged but are not fatal. The idea here is
+  to make consumers
   safe to decorate without having to duplicate the error handling logic.
 - [BC BREAK] `PMG\Queue\Serializer\SigningSerializer` has been merged into
   `NativeSerializer` and removed. Pass your key as the first argument to
   `NativeSerializer`'s constructor.
 - [BC BREAK] `AbstractPersistanceDriver::getSerializer` was removed, use
   `AbstractPersistanceDriver::assureSerializer` instead.
-- [BC BREAK] `Consumer::stop` now takes an optional exit code. Only really
-  relevant for implementors or the `Consumer` interface.
+- [BC BREAK] `Consumer::stop` now takes an optional exit code. This is mainly
+  relevant for implementers of the `Consumer` interface.
 - [BC BREAK] `MessageExecutor`, `HandlerResolver`, and their implementations
   have been removed. See `UPGRADE-3.0.md` for some info on migration.
 - `Consumer` has docblocks that reflect its actual return values now.
@@ -253,7 +255,7 @@ BC Breaks:
 Bug Fixes:
 
 - `SigningSerializer` now uses `hash_equals` instead of strict equality. PHP 5.5
-  users will fallback on the Symfony 5.6 polyfill.
+  users will fall back to the Symfony 5.6 polyfill.
 
 New Features:
 
@@ -287,7 +289,7 @@ Bug Fixes:
 
 BC Breaks:
 
-- everything, completely refactored
+- Everything was refactored.
 
 New Features:
 

README.md

@@ -3,10 +3,10 @@
 
 # PMG\Queue
 
-`pmg/queue` is a production ready queue framework that powers many internal
+`pmg/queue` is a production-ready queue framework that powers many internal
 projects at [PMG](https://www.pmg.com/).
 
-It's simple and extensible a number of features we've found to be the most
-useful including automatic retries and multi-queue support.
+It is simple and extensible, with features we have found most useful,
+including automatic retries and multi-queue support.
 
 ## [Documentation](http://pmg-queue.readthedocs.io/en/latest/)

UPGRADE-3.0.md

@@ -10,16 +10,16 @@ The biggest change is the extraction of the `PheanstalkDriver` into its own
 library. Rather than `composer require pmg/queue`, you'll want to require the
 pheanstalk driver instead: `composer require pmg/queue-pheanstalk`.
 
-## Introduction of `MessageHandler` and removal of Exectors & Resolvers
+## Introduction of `MessageHandler` and Removal of Executors & Resolvers
 
-Previously you gave the consumer an instance of a `MessageExector` that wrapped
+Previously, you gave the consumer an instance of a `MessageExecutor` that wrapped
 up a `HandlerResolver`. The point of this was to map callables to message names.
 
-In 3.0, we replace those two things with a single `MessageHandler` interface.
-There are two built in: a `CallableHandler` and `PcntlForkingHandler`.
+In 3.0, those two pieces are replaced by a single `MessageHandler` interface.
+There are two built-in options: a `CallableHandler` and `PcntlForkingHandler`.
 
-This was done to better reflect how PMG is using the Queue (and how we think it
-should be used).
+This change better reflects how PMG uses Queue and how we think it should be
+used.
 
 ### 2.X
 
@@ -65,7 +65,7 @@ No problem, it was moved into its own library.
 composer require pmg/queue-mapping-handler
 ```
 
-And use it like so:
+Use it like this:
 
 ```php
 use PMG\Queue as Q;

UPGRADE-4.0.md

@@ -2,12 +2,12 @@
 
 ## PHP Version Requirement Bumped to ~7.0
 
-Support for PHP 5.6+ dropped. Stick with 3.X need PHP 5 support is still
+Support for PHP 5.6+ was dropped. Stick with 3.X if PHP 5 support is still
 necessary.
 
 ## `NativeSerializer` Now Requires a `Signer` Instance
 
-Previously one could pass a key to `NativeSerializer` directly. Now a `Signer`
+Previously, you could pass a key to `NativeSerializer` directly. Now a `Signer`
 instance is required. A named constructor is provided if the 3.X behavior is
 still desired.
 
@@ -33,9 +33,9 @@ for more info.
 
 ## For Handler Authors
 
-Implementation of `MessageHandler` now requires a `GuzzleHttp\Promise\PromiseInterface`
-be returned from the `handle` method. This lets consumers do much more graceful
-stopping. If your handler does not *really* need a promise, use `FulfilledPromise`:
+Implementing `MessageHandler` now requires returning a `GuzzleHttp\Promise\PromiseInterface`
+from the `handle` method. This lets consumers stop much more gracefully.
+If your handler does not *really* need a promise, use `FulfilledPromise`:
 
 ```php
 use GuzzleHttp\Promise\FulfilledPromise;
@@ -62,7 +62,7 @@ for the updated method signatures.
 
 ### `Driver::release` was Added
 
-This is a method that should skip the retry system for the given
+This method should skip the retry system for the given
 envelope/message and put it back into a ready state immediately.
 
 ### `assureSerializer` was renamed in `AbstractPersistanceDriver`

UPGRADE-5.0.md

@@ -2,22 +2,23 @@
 
 ## PHP Version Requirement Bumped to ~7.3
 
-Stick with version 4.X should PHP 7.0, 7.1, or 7.2 support be required.
+Stick with version 4.X if PHP 7.0, 7.1, or 7.2 support is required.
 
 ## Messages No Longer Need to Implement `PMG\Queue\Message`
 
-Producers and consumers can now deal with plain objects. By default the *message name*
-for plain object messgaes is the fully qualified class name (FQCN).
+Producers and consumers can now deal with plain objects. By default, the
+*message name* for plain object messages is the fully qualified class name
+(FQCN).
 
 You may, however, implement `PMG\Queue\Message` (and its `getName` method) should
 you want to continue using message names other than FQCNs.
 
-The `PMG\Queue\MessageTrait` which provided the FQCN as a name behavior was also
+The `PMG\Queue\MessageTrait`, which provided FQCN-based naming, was also
 removed.
 
 ### Router Updates for Message Names
 
-The producers routing configuration may need to be updated should you choose to
+The producer's routing configuration may need to be updated should you choose to
 use FQCNs as the message names.
 
 #### Version 4.X
@@ -43,8 +44,8 @@ $router = new MappingRouter([
 
 ## `MessageLifecycle` Has a New `retrying` Method
 
-Rather than have an `$isRetrying` flag in the `failed` method. If the message is
-being retried the `retrying` method will be invoked, otherwise `failed` will.
+Instead of using an `$isRetrying` flag in the `failed` method, the consumer now
+calls `retrying` when a message is being retried and `failed` otherwise.
 
 This should be a pretty easy upgrade:
 
@@ -127,9 +128,9 @@ final class CustomRouter implements Router
 }
 ```
 
-## `MessageHandler::handle` Now Accept an Object
+## `MessageHandler::handle` Now Accepts an Object
 
-Any custom implementation of `MessageHandler` will need to be udpated.
+Any custom implementation of `MessageHandler` will need to be updated.
 
 ```diff
  use GuzzleHttp\Promise\PromiseInterface;
@@ -156,8 +157,8 @@ All changes here are only relevant to authors of `PMG\Queue\Driver`,
 
 And `send` now has a `void` return type as well.
 
-This is part of a broader change (see above) around pmg/queue dealing with
-plain `object` without the requirement of a `Message` implementation.
+This is part of a broader change (see above) around `pmg/queue` handling plain
+objects without requiring a `Message` implementation.
 
 ```diff
 -use PMG\Queue\Message;
@@ -177,7 +178,7 @@ plain `object` without the requirement of a `Message` implementation.
 ### `Driver::enqueue` Now Takes an `object` Instead of a `Message`
 
 Drivers should handle receiving an `Envelope` instance in this method as well.
-Should that happen the driver *must* use that envelope instead of creating its
+If that happens, the driver *must* use that envelope instead of creating its
 own.
 
 
@@ -209,7 +210,7 @@ own.
 In 4.X (and lower) drivers were required to call `$envelope->retry()` on any
 envelope passed in `Driver::retry`.
 
-That should now happen in implements of `PMG\Queue\Consumer` instead.
+That should now happen in implementations of `PMG\Queue\Consumer` instead.
 
 #### Version 4.X Driver
 

UPGRADE-6.0.md

@@ -2,7 +2,7 @@
 
 ## PHP Version Requirement Bumped to ^8.0
 
-Stick with version 5.X should PHP ^7.3 support be required.
+Stick with version 5.X if PHP ^7.3 support is required.
 
 ## Lifecycle Changes
 
@@ -17,5 +17,5 @@ Stick with version 5.X should PHP ^7.3 support be required.
 
 ## MessageTrait
 
-- `PMG\Queue\MessageTrait` was removed, the default behavior has been to use the
-  FQCN since 5.X, so this added no additional functionalty.
+- `PMG\Queue\MessageTrait` was removed. The default behavior has been to use the
+  FQCN since 5.X, so this added no additional functionality.