Docs clarification

Author: viktorprogger

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

@@ -57,9 +57,7 @@ As you can see in the [PHP documentation](https://www.php.net/manual/en/language
 
 ## Type 2: Callable definition extensions (via container)
 
-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 needed).  
+The difference from native PHP callables is that you don't need to instantiate objects yourself: you pass a class name or alias, and the DI container resolves the instance lazily, only when the callable is actually invoked.
 Ways to define an extended callable:
 
 - An object method through a class name or alias:
@@ -76,14 +74,17 @@ Ways to define an extended callable:
 
   $callable = [Foo::class, 'bar'];
   ```
-  Here is a simplified example of how it works:
+  Here is a simplified example of how it works (for non-static methods):
   ```php
   if ($container->has($callable[0])) {
     $callable[0] = $container->get($callable[0])
   }
-  
+
   $callable();
   ```
+
+> [!NOTE]
+> If `bar` is declared `static`, no object is instantiated — the method is called statically on the class.
 - Class name of an object with [the `__invoke` method](https://www.php.net/manual/en/language.oop5.magic.php#object.invoke) implemented:
   ```php
   $callable = Foo::class;

docs/guide/en/console-commands.md

@@ -6,6 +6,8 @@ If you are using [yiisoft/config](https://github.com/yiisoft/config) and [yiisof
 
 If you are using [symfony/console](https://github.com/symfony/console) directly, you should register the commands manually.
 
+> **Note:** The default queue name list (used when no queue names are passed to a command) is only available when using [yiisoft/config](https://github.com/yiisoft/config) and [yiisoft/yii-console](https://github.com/yiisoft/yii-console). Without them, you must pass the queue name list explicitly to the command constructor.
+
 In [yiisoft/app](https://github.com/yiisoft/app) the `yii` console binary is provided out of the box.
 If you are using [yiisoft/console](https://github.com/yiisoft/console) or `symfony/console` without that template, invoke these commands the same way you invoke other console commands in your application.
 
@@ -15,7 +17,7 @@ The command `queue:run` obtains and handles messages until the queue is empty, t
 
 You can also narrow the scope of processed messages by specifying queue name(s) and maximum number of messages to process:
 
-- Specify one or more queue names to process. Messages from other queues will be ignored. Default is all registered queue names (in case of using [yiisoft/config](https://github.com/yiisoft/config) and [yiisoft/yii-console](https://github.com/yiisoft/yii-console), otherwise pass the default queue name list to the command constructor).
+- Specify one or more queue names to process. Messages from other queues will be ignored. Defaults to all registered queue names.
 - Use `--limit` to limit the number of messages processed. When set, command will exit either when all the messages are processed or when the maximum count is reached.
 
 The full command signature is:
@@ -35,12 +37,10 @@ yii queue:listen [queueName]
 
 The following command iterates through multiple queues and is meant to be used in development environment only, as it consumes a lot of CPU for iterating through queues. You can pass to it:
 
-- `queueName` argument(s). Specify one or more queue names to process. Messages from other queues will be ignored. Default is all registered queue names (in case of using [yiisoft/config](https://github.com/yiisoft/config) and [yiisoft/yii-console](https://github.com/yiisoft/yii-console), otherwise pass the default queue name list to the command constructor).
+- `queueName` argument(s). Specify one or more queue names to process. Messages from other queues will be ignored. Defaults to all registered queue names.
 - `--limit` option to limit the number of messages processed before switching to another queue. E.g. you set `--limit` to 500 and right now you have 1000 messages in `queue1`. This command will consume only 500 of them, then it will switch to `queue2` to see if there are any messages there. Defaults to `0` (no limit).
 - `--pause` option to specify the number of seconds to pause between checking queues when no messages are found. Defaults to `1`.
 
-`queue:listen` does not have a `--limit` option. If you need to stop after processing a certain number of messages, use `queue:run --limit=...`.
-
 The full command signature is:
 ```sh
 yii queue:listen-all [queueName1 [queueName2 [...]]] --pause=1 --limit=0

docs/guide/en/envelopes.md

@@ -6,7 +6,7 @@ An envelope implements `Yiisoft\Queue\Message\EnvelopeInterface`, which itself e
 
 ## How an envelope behaves
 
-An envelope acts like the wrapped message:
+An envelope is transparent to callers: it delegates the wrapped message's handler name and data unchanged.
 
 - `getHandlerName()` is delegated to the wrapped message.
 - `getData()` is delegated to the wrapped message.

docs/guide/en/message-handler-simple.md

@@ -33,13 +33,12 @@ final class RemoteFileHandler implements \Yiisoft\Queue\Message\MessageHandlerIn
 **Pros**:
 
 - Minimal configuration.
-- Rename-safe within the same application (rename class and producer together).
+- Rename-safe within the same application (rename both the class and the message creation code together).
 - Easy to unit-test the handler as a normal class.
 
 **Cons**:
 
-- Couples message names to PHP class names.
-- Requires producer and consumer to share the same naming contract (typically the same app).
+- Message names are PHP class names — works only when message creation and handler live in the same codebase.
 
 **Use when**:
 

docs/guide/en/message-handler.md

@@ -1,8 +1,8 @@
 # Message handler advanced
 
-This page covers named handler definitions, callable formats, pitfalls, and recommended implementation styles.
+This page covers named handler definitions, callable formats, pitfalls, and valid handler signatures.
 
-For the zero-config FQCN approach (same-app producer and consumer), see [Message handler: simple setup](message-handler-simple.md).
+If you haven't read [Message handler: simple setup](message-handler-simple.md) yet, start there — it introduces handler classes and the zero-config FQCN approach.
 For a conceptual overview of what messages and handlers are, see [Messages and handlers: concepts](messages-and-handlers.md).
 
 Handler definitions are configured in:
@@ -36,9 +36,8 @@ return [
 ];
 ```
 
-Handler definition should be either an [extended callable definition](./callable-definitions-extended.md) or a string for your DI container to resolve a `MessageHandlerInterface` instance.
+Handler definition should be either an [extended callable definition](./callable-definitions-extended.md) or a container identifier that resolves to a `MessageHandlerInterface` instance.
 
-For the simpler FQCN-based approach that requires no mapping, see [Message handler: simple setup](message-handler-simple.md).
 
 ## When mapping by short names is a better idea
 
@@ -65,18 +64,18 @@ This way external producers never need to know your internal PHP class names.
 
 ## Common pitfalls and unsupported formats
 
-- A class-string that is not resolvable via `$container->has()` will not be auto-instantiated.
+- A PHP class name that is not registered in the DI container will not be auto-instantiated.
 - [yiisoft/definitions](https://github.com/yiisoft/definitions) array format (like `['class' => ..., '__construct()' => ...]`) is **not** supported for handlers.
 
-## Recommended handler implementation styles
+## Valid handler signatures
 
-- Prefer a dedicated handler class registered in DI.
-- For maximal compatibility with the worker resolution rules either:
-  - Implement `MessageHandlerInterface`
-  - Make the handler invokable (`__invoke(MessageInterface $message): void`)
-  - Provide `[HandlerClass::class, 'handle']` and keep `handle(MessageInterface $message): void` as the entry point
+The worker recognises three callable signatures:
 
-## Config location ([yiisoft/config](https://github.com/yiisoft/config))
+- `MessageHandlerInterface` — implement the interface; the worker calls `handle(MessageInterface $message): void` directly (covered in [simple setup](message-handler-simple.md)).
+- Invokable class — add `__invoke(MessageInterface $message): void`.
+- Explicit method — reference as `[HandlerClass::class, 'handle']` with `handle(MessageInterface $message): void` as the entry point.
+
+## Config location (yiisoft/config)
 
 When using [yiisoft/config](https://github.com/yiisoft/config), configure handlers under the [`yiisoft/queue`](https://github.com/yiisoft/queue) params key:
 
@@ -90,4 +89,4 @@ return [
 ];
 ```
 
-This config is consumed by the DI definitions from `config/di.php` where the `Worker` is constructed with `$params['yiisoft/queue']['handlers']`.
+This config is consumed by the DI definitions from [`config/di.php`](../../../config/di.php) where the `Worker` is constructed with `$params['yiisoft/queue']['handlers']`.

docs/guide/en/migrating-from-yii2-queue.md

@@ -23,8 +23,8 @@ being consumed. In the new package, it is divided into two different concepts: a
 
     All the message data is fully serializable (that means message `data` must be serializable too). It allows you to
     freely choose where and how to send and process messages. Both can be implemented in a single application, or
-    separated into multiple applications, or you can do sending/processing only leaving part of the work to another
-    system including non-PHP ones. It is fairly popular to process heavy messages with Go.
+    separated into multiple applications, or you can do sending/processing only, leaving part of the work to another
+    system including non-PHP ones (for example, a Go service handling CPU-intensive jobs).
 
 - A `Handler` is called by a `Worker` when a message is received. Default `Worker` finds a corresponding message handler
   by the message name. [See more](message-handler.md).

docs/guide/en/queue-names-advanced.md

@@ -1,6 +1,6 @@
 # Advanced queue name internals
 
-Use this reference when you need to understand how queue names map to adapters, how providers resolve queues, and how to extend the registry.
+Use this reference when you need to understand how queue names map to adapters, how providers resolve queues, and how to implement your own provider.
 
 ## How queue names are used in code
 
@@ -23,7 +23,7 @@ This package ships four provider strategies:
 - Backed by the `yiisoft/queue.queues` params array.
 - Each queue name maps to an adapter definition.
 - Uses `yiisoft/factory` to create adapters lazily, then wraps them in a `Queue` with the given name.
-- Enforces a strict registry: unknown queue names throw `QueueNotFoundException` immediately.
+- Enforces a strict name mapping: unknown queue names throw `QueueNotFoundException` immediately.
 
 ### PredefinedQueueProvider
 
@@ -70,7 +70,7 @@ $queueForEmails = $provider->get('emails');
 
 - Accepts multiple providers and queries them in order.
 - The first provider whose `has()` returns true for the queue name wins.
-- Useful for mixing strict registries with pre-built queues.
+- Useful for mixing multiple providers, for example combining adapter-based and pre-built queues.
 
 Example:
 
@@ -87,8 +87,8 @@ $provider = new CompositeQueueProvider(
 $queueForEmails = $provider->get('emails');
 ```
 
-## Extending the registry
+## Implementing a custom provider
 
-- Implement `QueueProviderInterface` if you need bespoke selection logic (e.g., tenant-specific registries, remote lookups, or metrics-aware routing).
+- Implement `QueueProviderInterface` if you need bespoke selection logic (e.g., tenant-specific routing, remote lookups, or metrics-aware routing).
 - Register your provider in the DI container and swap it in wherever `QueueProviderInterface` is used.
-- Consider exposing diagnostics (e.g., list of available queues) through `getNames()`, console commands, or health checks so operators can verify the registry at runtime.
+- Consider exposing diagnostics (e.g., list of available queues) through `getNames()`, console commands, or health checks so operators can verify the available queues at runtime.