Docs clarification

Author: viktorprogger

docs/guide/en/adapter-sync.md

@@ -1,7 +1,7 @@
 Synchronous Adapter
 ==================
 
-Run tasks synchronously in the same process. It could be used when developing and debugging an application.
+Run tasks synchronously in the same process. The adapter is intended for use when developing and debugging an application.
 
 Configuration example:
 

docs/guide/en/advanced-map.md

@@ -14,23 +14,21 @@ Use this index when you need to customize internals: custom middleware, adapters
 
 - [Middleware pipelines deep dive](middleware-pipelines.md) — dispatcher lifecycle, request mutations, and per-pipeline contracts.
 - [Callable definitions and middleware factories](callable-definitions-extended.md) — container-aware definitions for middleware factories.
-- [Error handling](error-handling.md#failure-pipeline-overview) — end-to-end flow of the failure pipeline.
+- [Error handling](error-handling.md#failure-handling-pipeline-overview-step-by-step) — end-to-end flow of the failure pipeline.
 - [Custom failure middleware](error-handling.md#how-to-create-a-custom-failure-middleware) — implementing `MiddlewareFailureInterface`.
 - [Envelope metadata and stack reconstruction](envelopes.md#metadata-and-envelope-stacking) — stack resolution and metadata merging.
 - [FailureEnvelope usage](error-handling.md#failureenvelope) — retry metadata semantics.
-- [Handler resolver pipeline](message-handler.md#resolver-pipeline) — alternative handler lookup strategies.
+- [Handler resolver pipeline](message-handler.md) — alternative handler lookup strategies.
 
 ## Queue adapters and interoperability
 
 - [Custom queue provider implementations](queue-names-advanced.md#extending-the-registry) — bespoke selection logic, tenant registries, and fallback strategies.
 - [Consuming messages from external systems](consuming-messages-from-external-systems.md) — contract for third-party producers.
-- [Adapter internals](adapter-list.md#available-adapters) — extend or swap backend adapters.
+- [Adapter internals](adapter-list.md) — extend or swap backend adapters.
 
-## Tooling, diagnostics, and storage
+## Tooling and diagnostics
 
 - [Yii Debug collector internals](debug-integration-advanced.md) — collector internals, proxies, and manual wiring.
-- [Message status storage extensions](message-status.md#extend-storage) — persisting custom metadata or drivers.
-- [Extending queue processes and supervisors](process-managers.md#custom-supervisors) — custom supervisor hooks and graceful shutdown integration.
 
 ## Internals and contribution
 

docs/guide/en/best-practices.md

@@ -53,7 +53,7 @@ final class ProcessPaymentHandler implements MessageHandlerInterface
 
 ### Keep message handlers stateless
 
-Avoid storing per-message state in handler properties. Handlers may be reused by the container and queue workers are often long-running processes.
+Avoid storing per-message state in handler properties. The container may return the same handler instance for multiple consecutive messages, so handlers should not store state between invocations. Queue workers are often long-running processes, which amplifies this issue.
 
 #### Bad
 
@@ -452,7 +452,7 @@ use Yiisoft\Queue\Cli\SignalLoop;
 return [
     SignalLoop::class => [
         '__construct()' => [
-            'memorySoftLimit' => 256 * 1024 * 1024, // 200MB, lower than a hard limit of 256MB
+            'memorySoftLimit' => 200 * 1024 * 1024, // 200MB, lower than a hard limit of 256MB
         ],
     ],
 ];

docs/guide/en/callable-definitions-extended.md

@@ -1,6 +1,6 @@
 # Callable Definitions Extended
 
-Callable definitions in `yiisoft/queue` are based on [native PHP callables](https://www.php.net/manual/en/language.types.callable.php) and suggest additonial ways to define a callable.
+Callable definitions in `yiisoft/queue` are based on [native PHP callables](https://www.php.net/manual/en/language.types.callable.php) and suggest additional ways to define a callable.
 
 Both definition types (classic callables and new ones) allow you to use a DI container and [yiisoft/injector](https://github.com/yiisoft/injector) to resolve dependencies in a lazy way.
 These callable definition formats are used across the package to convert configuration definitions into real callables.
@@ -16,7 +16,7 @@ As you can see in the [PHP documentation](https://www.php.net/manual/en/language
     // do stuff
   }
   ```
-- **First class callable**. It's a Closure too, BTW ;) Example:
+- **First class callable**. It is itself a `Closure`. Example:
   ```php
   $callable = trim(...);
   $callable2 = $this->foo(...);
@@ -30,8 +30,7 @@ As you can see in the [PHP documentation](https://www.php.net/manual/en/language
   $foo = new Foo();
   $callable = [$foo, 'bar']; // this will be called the same way as $foo->bar();
   ```
-- **A class static function as a string**. I don't recommend you to use this ability, as it's non-obvious and
-  hard to refactor, but it still exists:
+- **A class static function as a string**. This format is non-obvious and hard to refactor; it exists for completeness only:
   ```php
   $callable = 'Foo::bar'; // this will be called the same way as Foo::bar();
   ```
@@ -60,7 +59,7 @@ As you can see in the [PHP documentation](https://www.php.net/manual/en/language
 
 Under the hood, extended callable definitions behave exactly like native callables. But there is a major difference:
 all the objects are instantiated automatically by a PSR-11 DI container with all their dependencies
-and in a lazy way (only when they are really needed).  
+and in a lazy way (only when they are needed).  
 Ways to define an extended callable:
 
 - An object method through a class name or alias:

docs/guide/en/configuration-manual.md

@@ -28,7 +28,7 @@ use Yiisoft\Queue\Middleware\Push\PushMiddlewareDispatcher;
 use Yiisoft\Queue\Queue;
 use Yiisoft\Queue\Worker\Worker;
 
-// A PSR-11 container is required for dependency resolution inside middleware and handlers.
+// A PSR-11 container is required for resolving dependencies of middleware and handlers.
 // How you build it is up to you.
 /** @var ContainerInterface $container */
 
@@ -81,7 +81,7 @@ $queue = new Queue(
 // SynchronousAdapter needs a queue reference — create it after the queue
 $adapter = new SynchronousAdapter($worker, $queue);
 
-// Wire the adapter in (returns a new Queue instance)
+// Attach the adapter to the queue (returns a new Queue instance)
 $queue = $queue->withAdapter($adapter);
 
 // Now you can push messages

docs/guide/en/console-commands.md

@@ -25,7 +25,7 @@ yii queue:run [queueName1 [queueName2 [...]]] --limit=100
 
 ## 2. Listen for queued messages and process them continuously
 
-The following command launches a daemon, which infinitely consumes messages from a single queue. This command receives an optional `queueName` argument to specify which queue to listen to, defaults to the default queue name `yii-queue`.
+The following command launches a daemon, which infinitely consumes messages from a single queue. This command receives an optional `queueName` argument to specify which queue to listen to, defaults to the queue name `yii-queue`.
 
 ```sh
 yii queue:listen [queueName]

docs/guide/en/consuming-messages-from-external-systems.md

@@ -70,7 +70,7 @@ Full example:
 
 ### Notes about `meta`
 
-The `meta` key is a general-purpose metadata container (for example, tracing, correlation, tenant information). The consumer-side application or middleware may read, add, or override keys as needed. Populating `meta` from external producers is possible but not recommended: the accepted keys and their semantics are entirely defined by the consumer application, so any contract must be maintained manually.
+The `meta` key is a general-purpose metadata container (for example, tracing, correlation, tenant information). The consumer-side application or middleware may read, add, or override keys as needed. Populating `meta` from external producers is possible but not recommended: the accepted keys and their semantics are entirely defined by the consumer application, so the mapping of field names and their expected values must be maintained manually.
 
 ## 3. Data encoding rules
 
@@ -84,7 +84,7 @@ If your broker stores bytes, publish the UTF-8 bytes of the JSON string.
 
 ## 4. Publishing to a broker: what exactly to send
 
-`yiisoft/queue` itself does not define a network protocol. The exact “where” this JSON goes depends on the adapter:
+`yiisoft/queue` itself does not define a network protocol. The exact destination or transport for this JSON depends on the adapter:
 
 - Some adapters put this JSON into the broker message **body**.
 - Some adapters may additionally use broker headers/attributes.

docs/guide/en/debug-integration-advanced.md

@@ -14,12 +14,12 @@ The integration is based on `Yiisoft\Queue\Debug\QueueCollector` and captures:
 
 The collector is enabled by registering it in Yii Debug and wrapping tracked services with proxy implementations.
 
-Out of the box (see this package's `config/params.php`), the following services are intercepted:
+Out of the box (see this package's `config/params.php`), the following services are wrapped:
 
 - `Yiisoft\Queue\Provider\QueueProviderInterface` is wrapped with `Yiisoft\Queue\Debug\QueueProviderInterfaceProxy`. The proxy decorates returned queues with `Yiisoft\Queue\Debug\QueueDecorator` so that `push()` and `status()` calls are reported to the collector.
 - `Yiisoft\Queue\Worker\WorkerInterface` is wrapped with `Yiisoft\Queue\Debug\QueueWorkerInterfaceProxy` to record message processing events.
 
-To see data in the debug panel you must obtain `QueueProviderInterface` and `WorkerInterface` from the DI container so that the proxies remain in effect.
+To see data in the debug panel, obtain `QueueProviderInterface` and `WorkerInterface` from the DI container — the debug proxies are registered there and will not be active if the services are instantiated directly.
 
 ## Manual configuration
 

docs/guide/en/envelopes.md

@@ -11,7 +11,7 @@ An envelope acts like the wrapped message:
 - `getHandlerName()` is delegated to the wrapped message.
 - `getData()` is delegated to the wrapped message.
 
-What an envelope adds is `getMetadata()`.
+Envelopes modify the metadata returned by `getMetadata()` and may provide convenience methods for accessing specific metadata entries (for example, `getId()` in an ID envelope).
 
 ## Metadata and envelope stacking
 
@@ -22,7 +22,7 @@ Every envelope contributes its own metadata to the resulting metadata array.
 When `getMetadata()` is called on an envelope, it returns:
 
 - the wrapped message metadata,
-- plus an updated `"envelopes"` stack (previous stack + current envelope class),
+- plus an updated `"envelopes"` stack (previous stack + current envelope's FQCN),
 - plus envelope-specific metadata.
 
 Because envelopes wrap other messages, multiple envelopes form a stack.
@@ -39,12 +39,12 @@ and, via `MessageInterface` inheritance, also support:
 
 ## Restoring envelopes from metadata
 
-If metadata contains the `"envelopes"` key with an array of envelope class names, the serializer will try to rebuild the stack by wrapping the message with each envelope class in the given order.
+If metadata contains the `"envelopes"` key with an array of envelope class names, the serializer will try to rebuild the stack by wrapping the message with each envelope in reverse order.
 
 During this process:
 
 - The `"envelopes"` key is removed from the base message metadata (it is set to an empty array before creating the base message).
-- Each envelope class from the list is applied to the message using `EnvelopeInterface::fromMessage(...)`.
+- Each envelope from the list is applied to the message using `EnvelopeInterface::fromMessage(...)` in reverse order.
 - A value is applied only if it is a string, the class exists, and it implements `EnvelopeInterface`. Otherwise it is ignored.
 
 ## Built-in envelopes

docs/guide/en/error-handling.md

@@ -1,6 +1,6 @@
 # Error handling on message processing
 
-Often when message handling fails, we want to retry it a couple more times or redirect it to another queue. In `yiisoft/queue` this is handled by the failure handling middleware pipeline.
+Often when message handling fails, we want to retry the message a couple more times or redirect it to another queue. In `yiisoft/queue` this is handled by the failure handling middleware pipeline.
 
 ## When failure handling is triggered
 
@@ -64,7 +64,7 @@ In practice, built-in middlewares handle failures by re-queueing the message (sa
 
 ## Configuration
 
-Here below is configuration via [yiisoft/config](https://github.com/yiisoft/config) (see also [Configuration with yiisoft/config](configuration-with-config.md)). If you don't use it, you should add a middleware definition list (in the `middlewares-fail` key here) to the `FailureMiddlewareDispatcher` [by your own](configuration-manual.md). You can define different failure handling pipelines for each queue name (see [Queue names](queue-names.md)). The example below defines two different failure handling pipelines:
+Here below is configuration via [yiisoft/config](https://github.com/yiisoft/config) (see also [Configuration with yiisoft/config](configuration-with-config.md)). If you don't use it, you should add a middleware definition list (in the `middlewares-fail` key here) to the `FailureMiddlewareDispatcher` [yourself](configuration-manual.md). You can define different failure handling pipelines for each queue name (see [Queue names](queue-names.md)). The example below defines two different failure handling pipelines:
 
 ```php
 'yiisoft/queue' => [
@@ -114,7 +114,7 @@ In the example above failures will be handled this way (look the concrete middle
 3. From now on it will be resent to the same queue (`failed-messages`) up to 30 times with a delay from 5 to 60 seconds, increased 1.5 times each time the message fails again.
 4. If the message handler throw an exception one more (33rd) time, the exception will not be caught.
 
-Failures of messages, which are initially sent to the `failed-messages` queue, will only be handled by the 3rd and the 4th points of this list.
+Failures of messages that arrived in the `failed-messages` queue directly (bypassing the error-handling pipeline) will only be handled by the 3rd and the 4th points of this list.
 
 ## Default failure handling strategies
 
@@ -197,6 +197,6 @@ This interface has the only method `handle` with these parameters:
     - a [message](../../../src/Message/MessageInterface.php)
     - a `Throwable $exception` object thrown on the `request` handling
     - a queue the message came from
-- `MessageFailureHandlerInterface $handler` - failure strategy pipeline continuation. Your Middleware should call `$pipeline->handle()` when it shouldn't interrupt failure pipeline execution.
+- `MessageFailureHandlerInterface $handler` - failure strategy pipeline continuation. Your Middleware should call `$pipeline->handle()` when the middleware itself should not interrupt failure pipeline execution.
 
-> Note: your strategy have to check by its own if it should be applied. Look into [`SendAgainMiddleware::suites()`](../../../src/Middleware/FailureHandling/Implementation/SendAgainMiddleware.php#L54) for an example.
+> Note: your strategy have to check by its own if it should be applied. Look into [`SendAgainMiddleware::suits()`](../../../src/Middleware/FailureHandling/Implementation/SendAgainMiddleware.php#L54) for an example.