Fix #372 by adding listener matcher docs (#402)

Author: seratch

docs/_advanced/ja_listener_middleware.md

@@ -7,10 +7,13 @@ order: 5
 
 <div class="section-content">
 リスナーミドルウェアは、それを渡したリスナーでのみ実行されるミドルウェアです。リスナーには、`middleware` パラメーターを使ってミドルウェア関数をいくつでも渡すことができます。このパラメーターには、1 つまたは複数のミドルウェア関数からなるリストを指定します。
+
+非常にシンプルなリスナーミドルウェアの場合であれば、`next()` メソッドを呼び出す代わりに `bool` 値（処理を継続したい場合は `True`）を返すだけで済む「リスナーマッチャー」を使うとよいでしょう。
 </div>
 
 <div>
 <span class="annotation">指定可能な引数の一覧は<a href="https://slack.dev/bolt-python/api-docs/slack_bolt/kwargs_injection/args.html" target="_blank">モジュールドキュメント</a>を参考にしてください。</span>
+
 ```python
 # "bot_message" サブタイプのメッセージを抽出するリスナーミドルウェア
 def no_bot_messages(message, next):
@@ -21,7 +24,18 @@ def no_bot_messages(message, next):
 # このリスナーは人間によって送信されたメッセージのみを受け取ります
 @app.event(event="message", middleware=[no_bot_messages])
 def log_message(logger, event):
-    logger.info(f"(MSG) User: {event['user']}
-Message: {event['text']}")
+    logger.info(f"(MSG) User: {event['user']}\nMessage: {event['text']}")
+
+# リスナーマッチャー： 簡略化されたバージョンのリスナーミドルウェア
+def no_bot_messages(message) -> bool:
+    return message.get("subtype") != "bot_message"
+
+@app.event(
+    event="message", 
+    matchers=[no_bot_messages]
+    # or matchers=[lambda message: message.get("subtype") != "bot_message"]
+)
+def log_message(logger, event):
+    logger.info(f"(MSG) User: {event['user']}\nMessage: {event['text']}")
 ```
 </div>

docs/_advanced/listener_middleware.md

@@ -7,10 +7,13 @@ order: 5
 
 <div class="section-content">
 Listener middleware is only run for the listener in which it's passed. You can pass any number of middleware functions to the listener using the `middleware` parameter, which must be a list that contains one to many middleware functions.
+
+If your listener middleware is a quite simple one, you can use a listener matcher, which returns `bool` value (`True` for proceeding) instead of requiring `next()` method call.
 </div>
 
 <div>
 <span class="annotation">Refer to <a href="https://slack.dev/bolt-python/api-docs/slack_bolt/kwargs_injection/args.html" target="_blank">the module document</a> to learn the available listener arguments.</span>
+
 ```python
 # Listener middleware which filters out messages with "bot_message" subtype
 def no_bot_messages(message, next):
@@ -20,6 +23,18 @@ def no_bot_messages(message, next):
 
 # This listener only receives messages from humans
 @app.event(event="message", middleware=[no_bot_messages])
+def log_message(logger, event):
+    logger.info(f"(MSG) User: {event['user']}\nMessage: {event['text']}")
+
+# Listener matchers: simplified version of listener middleware
+def no_bot_messages(message) -> bool:
+    return message.get("subtype") != "bot_message"
+
+@app.event(
+    event="message", 
+    matchers=[no_bot_messages]
+    # or matchers=[lambda message: message.get("subtype") != "bot_message"]
+)
 def log_message(logger, event):
     logger.info(f"(MSG) User: {event['user']}\nMessage: {event['text']}")
 ```