symfony
diff --git a/‎messenger.rst
Copy file name to clipboardExpand all lines: messenger.rst
+29-27Lines changed: 29 additions & 27 deletions b/‎messenger.rst
Copy file name to clipboardExpand all lines: messenger.rst
+29-27Lines changed: 29 additions & 27 deletions
@@ -276,37 +276,37 @@ you can disable them like this:
 Using Middleware Factories
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Some third-parties may expose you configurable middleware by using factories.
-Such factories are actually relying on the Symfony DI capabilities and consist
-of this kind of two services:
+Sometimes middleware are configurable using factories. There are two types of
+factories and they are based on Symfony's :doc:`dependency injection </service_container>`
+features:
 
 .. code-block:: yaml
 
     services:
 
-        # A factory class is registered as a service with required dependencies
-        # to instantiate a middleware:
+        # Type 1: a factory class is registered as a service with the required
+        # dependencies to instantiate a middleware
         doctrine.orm.messenger.middleware_factory.transaction:
-          class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory
-          arguments: ['@doctrine']
+            class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory
+            arguments: ['@doctrine']
 
-        # An abstract definition that will call the factory with default arguments
-        # or the one provided in the middleware config:
+        # Type 2: an abstract definition that will call the factory with default arguments
+        # or the one provided in the middleware config
         messenger.middleware.doctrine_transaction_middleware:
-          class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddleware
-          factory: ['@doctrine.orm.messenger.middleware_factory.transaction', 'createMiddleware']
-          abstract: true
-          # the default arguments to use when none provided from config.
-          # i.e:
-          #   middleware:
-          #     - doctrine_transaction_middleware: ~
-          arguments: ['default']
+            class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddleware
+            factory: ['@doctrine.orm.messenger.middleware_factory.transaction', 'createMiddleware']
+            abstract: true
+            # the default arguments to use when none provided from config. Example:
+            # middleware:
+            #     - doctrine_transaction_middleware: ~
+            arguments: ['default']
 
-The "default" value in this example corresponds to the entity manager name to use, as expected by the
-``Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory::createMiddleware`` method as argument.
+The "default" value in this example is the name of the entity manager to use,
+which is the argument expected by the
+``Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory::createMiddleware`` method.
 
-Then you can reference and configure the ``messenger.middleware.doctrine_transaction_middleware``
-service as a middleware:
+Then you can reference and configure the
+``messenger.middleware.doctrine_transaction_middleware`` service as a middleware:
 
 .. configuration-block::
 
@@ -368,18 +368,20 @@ service as a middleware:
 
 .. note::
 
-    The shorthand ``doctrine_transaction_middleware`` name can be used by convention,
-    as the service id is prefixed with the ``messenger.middleware.`` namespace.
+    The ``doctrine_transaction_middleware`` shortcut is a convention. The real
+    service id is prefixed with the ``messenger.middleware.`` namespace.
 
 .. note::
 
-    Middleware factories only allow scalar and array arguments in config (no service reference).
-    For most advanced use-cases, register a concrete definition of the middleware yourself and use its id.
+    Middleware factories only allow scalar and array arguments in config (no
+    references to other services). For most advanced use-cases, register a
+    concrete definition of the middleware manually and use its id.
 
 .. tip::
 
-    The ``doctrine_transaction_middleware`` is an existing middleware wired
-    by the DoctrineBundle if installed and the Messenger component enabled.
+    The ``doctrine_transaction_middleware`` is a built-in middleware wired
+    automatically when the DoctrineBundle and the Messenger component are
+    installed and enabled.
 
 Your own Transport
 ------------------