From 2a731f7ce28d46a65d8614630deb267172a1f565 Mon Sep 17 00:00:00 2001
From: Alex Root Junior <jroot.junior@gmail.com>
Date: Sat, 30 Nov 2019 00:43:19 +0200
Subject: [PATCH] Update filters doc page

---
 docs/dispatcher/filters/base.md  |  0
 docs/dispatcher/filters/index.md | 60 ++++++++++++++++++++++++++++++--
 docs/dispatcher/observer.md      |  2 +-
 mkdocs.yml                       |  1 -
 4 files changed, 58 insertions(+), 5 deletions(-)
 delete mode 100644 docs/dispatcher/filters/base.md

diff --git a/docs/dispatcher/filters/base.md b/docs/dispatcher/filters/base.md
deleted file mode 100644
index e69de29b..00000000
diff --git a/docs/dispatcher/filters/index.md b/docs/dispatcher/filters/index.md
index 10ad50ec..233bd767 100644
--- a/docs/dispatcher/filters/index.md
+++ b/docs/dispatcher/filters/index.md
@@ -1,7 +1,61 @@
-# Overview
+# Basics
 
+Filters is needed for routing updates to the specific handler.
+Searching of handler is always stops on first match set of filters are pass. 
 
-## Writing own filters
-
+`aiogram` has some builtin useful filters.
 
 ## Builtin filters
+
+Here is list of builtin filters and event types where it can be used:
+
+| Filter                      | update | message | edited_message | channel_post | edited_channel_post | inline_query | chosen_inline_result | callback_query | shipping_query | pre_checkout_query | poll |
+| --------------------------- |:------:|:-------:|:--------------:|:------------:|:-------------------:|:------------:|:--------------------:|:--------------:|:--------------:|:------------------:|:----:|
+| [Text](text.md)             |        | +       | +              | +            | +                   | +            |                      | +              |                |                    | +    |
+|                             |        |         |                |              |                     |              |                      |                |                |                    |      |
+
+
+## Own filters specification
+
+Filters can be:
+
+- Asynchronous function (`#!python3 async def my_filter(*args, **kwargs): pass`)
+- Synchronous function (`#!python3 def my_filter(*args, **kwargs): pass`)
+- Anonymous function (`#!python3 lambda event: True`)
+- Any awaitable object
+- Subclass of `BaseFilter`
+
+Filters should return bool or dict. 
+If the dictionary is passed as result of filter - resulted data will be propagated to the next 
+filters and handler as keywords arguments.
+
+## Writing bound filters
+
+If you want to register own filters like builtin filters you will need to write subclass 
+of BaseFilter (`#!python3 from aiogram.filters import BaseFilter`) with overriding the `__call__` 
+method and adding filter attributes.
+
+BaseFilter is subclass of `pydantic.BaseModel` that's mean all subclasses of BaseFilter has 
+the validators based on class attributes and custom validator.
+
+For example if you need to make simple text filter:
+
+```python3
+from aiogram.filters import BaseFilter
+
+
+class MyText(BaseFilter):
+    my_text: str
+
+    async def __call__(self, message: Message) -> bool:
+        return message.text == self.my_text
+
+
+router.message_handler.bind_filter(MyText)
+
+@router.message_handler(my_text="hello")
+async def my_handler(message: Message): ...
+``` 
+
+!!! info
+    Bound filters is always recursive propagates to the nested routers.
diff --git a/docs/dispatcher/observer.md b/docs/dispatcher/observer.md
index d4cc7796..222503e9 100644
--- a/docs/dispatcher/observer.md
+++ b/docs/dispatcher/observer.md
@@ -39,7 +39,7 @@ In this handler can be bounded filters which can be used as keyword arguments in
 
 ### Registering bound filters
 
-Bound filter should be subclass of [BaseFilter](filters/base.md)
+Bound filter should be subclass of [BaseFilter](filters/index.md)
 
 `#!python3 <observer>.bind_filter(MyFilter)`
 
diff --git a/mkdocs.yml b/mkdocs.yml
index 969c70ac..40e3b506 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -224,7 +224,6 @@ nav:
       - dispatcher/observer.md
       - Filters:
           - dispatcher/filters/index.md
-          - dispatcher/filters/base.md
           - dispatcher/filters/text.md
 
   - Build reports: