Add a documentation about middlewares and update based on reviews

Author: sroze

components/messenger.rst

@@ -38,9 +38,11 @@ Concepts
 Bus
 ---
 
-The bus is used to dispatch messages. MessageBus' behaviour is in its ordered
-middleware stack. When using the message bus with Symfony's FrameworkBundle, the
-following middlewares are configured for you:
+The bus is used to dispatch messages. The behaviour of the bus is in its ordered
+middleware stack. The component comes with a set of middlewares that you can use.
+
+When using the message bus with Symfony's FrameworkBundle, the following middlewares
+are configured for you:
 
 #. :code:`LoggingMiddleware` (logs the processing of your messages)
 #. :code:`SendMessageMiddleware` (enables asynchronous processing)
@@ -56,11 +58,15 @@ Example::
     $bus = new MessageBus([
         new HandleMessageMiddleware(new HandlerLocator([
             MyMessage::class => $handler,
-        ]))
+        ])),
     ]);
 
     $result = $bus->handle(new MyMessage(/* ... */));
 
+.. note:
+
+    Every middleware need to implement the :code:`MiddlewareInterface` interface.
+
 Handlers
 --------
 
@@ -87,11 +93,8 @@ Adapters
 The communication with queuing system or third parties is delegated to
 libraries for now.
 
-Create your adapter
-~~~~~~~~~~~~~~~~~~~
-
 Your own sender
----------------
+~~~~~~~~~~~~~~~
 
 Using the ``SenderInterface``, you can easily create your own message sender.
 Let's say you already have an ``ImportantAction`` message going through the
@@ -134,7 +137,7 @@ First, create your sender::
     }
 
 Your own receiver
------------------
+~~~~~~~~~~~~~~~~~
 
 A receiver is responsible for receiving messages from a source and dispatching
 them to the application.

messenger.rst

@@ -93,7 +93,7 @@ the messenger component, the following configuration should have been created:
             adapters:
                 default: "%env(MESSENGER_DSN)%"
 
-.. code-block:: env
+.. code-block:: bash
 
     # .env
     ###> symfony/messenger ###
@@ -169,6 +169,21 @@ like this:
 The first argument is the receiver's service name. It might have been created by
 your :code:`adapters` configuration or it can be your own receiver.
 
+Registering your middlewares
+----------------------------
+
+The message bus is based on middlewares. If you are un-familiar with the concept,
+look at the :doc:`Messenger component docs </components/messenger>`.
+
+To register your middleware, use the :code:`messenger.middleware` tag as in the
+following example:
+
+.. code-block:: xml
+
+    <service id="Your\Own\Middleware">
+       <tag name="messenger.middleware" />
+    </service>
+
 Your own Adapters
 -----------------