Improve docs

docs/advanced-usage/2-graceful-shutdown.md

@@ -5,7 +5,7 @@ weight: 2
 
 Stopping consumers is very useful if you want to ensure you don't kill a process halfway through processing a consumed message.
 
-Starting from version `1.12.x` of this package, consumers automatically listen to the `SIGTERM`, `SIGINT` and `SIQUIT` signals, which means you can easily stop your consumers using those signals.
+Consumers automatically listen to the `SIGTERM`, `SIGINT` and `SIQUIT` signals, which means you can easily stop your consumers using those signals.
 
 ### Running callbacks when the consumer stops
 If your app requires that you run sum sort of processing when the consumers stop processing messages, you can use the `onStopConsume` method, available on the `\Junges\Kafka\Contracts\CanConsumeMessages` interface. This method accepts a `Closure` that will run once your consumer stops consuming.
@@ -16,12 +16,12 @@ use Junges\Kafka\Facades\Kafka;
 $consumer = Kafka::consumer(['topic'])
     ->withConsumerGroupId('group')
     ->withHandler(new Handler)
-    ->build()
     ->onStopConsuming(static function () {
         // Do something when the consumer stop consuming messages
     })
+    ->build();
 
 $consumer->consume();
 ```
 
-> You will require the [ Process Control Extension ](https://www.php.net/manual/en/book.pcntl.php) to be installed to utilise this feature.
+> This features requires [ Process Control Extension ](https://www.php.net/manual/en/book.pcntl.php) to be installed.

docs/advanced-usage/6-stopping-a-consumer.md

@@ -0,0 +1,25 @@
+---
+title: Stop consumer on demand
+weight: 6
+---
+
+Sometimes, you may want to stop your consumer based on a given message or any other condition.
+
+You can do it by adding a calling `stopConsuming()` method on the `MessageConsumer` instance that is passed as the 
+second argument of your message handler:
+
+```php
+$consumer = \Junges\Kafka\Facades\Kafka::consumer(['topic'])
+    ->withConsumerGroupId('group')
+    ->stopAfterLastMessage()
+    ->withHandler(static function (\Junges\Kafka\Contracts\ConsumerMessage $message, \Junges\Kafka\Contracts\MessageConsumer $consumer) {
+        if ($someCondition) {
+            $consumer->stopConsuming();
+        }
+    })
+    ->build();
+
+$consumer->consume();
+```
+
+The `onStopConsuming` callback will be executed before stopping your consumer.