Completed doc and API reference for filters

Author: Sylvain MARIE

docs/api_reference.md

@@ -178,6 +178,61 @@ Returns True if the provided object is a function or callable and, if `check_pre
 
  - `check_prefix`: if this boolean is True (default), the prefix will be checked. If False, any function will lead to a `True` result whatever its name.
 
+### The `filters` submodule
+
+This submodule contains symbols to help you create filters for `@parametrize_with_cases(filter=...)`.
+
+All helper filters in this submodule return an instance of `CaseFilter`, so that you can combine them easily with "and" (`&`) "or" (`|`) and "invert" (`~`) in order to create new custom filters.
+
+#### `has_tag`
+
+```python
+def has_tag(tag_name: str)
+```
+
+Selects cases that have the tag `tag_name`. See `@case(tags=...)` to add tags to a case.
+
+#### `has_tags`
+
+```python
+def has_tags(*tag_names: str)
+```
+
+Selects cases that have all tags `tag_names`. See `@case(tags=...)` to add tags to a case.
+
+#### `id_has_prefix`
+
+```python
+def id_has_prefix(prefix: str)
+```
+
+Selects cases that have a case id prefix `prefix`. Note that this is not the prefix of the whole case function name, but the case id, possibly overridden with `@case(id=)`
+
+#### `id_has_suffix`
+
+```python
+def id_has_suffix(suffix: str)
+```
+
+Selects cases that have a case id suffix `suffix`. Note that this is not the suffix of the whole case function name, but the case id, possibly overridden with `@case(id=)`
+
+
+#### `id_match_regex`
+
+```python
+def id_match_regex(regex: str)
+```
+
+Selects cases that have a case id matching regex pattern `regex`. Note that this is not a match of the whole case function name, but the case id, possibly overridden with `@case(id=)`
+
+#### `CaseFilter`
+
+```python
+CaseFilter(filter_function: Callable)
+```
+
+`CaseFilter` is the class used by all filters above, and implementing logical operations "and" (`&`) "or" (`|`) and "not" (`~`). You can use it to define a composable filter from any callable receiving a single `case` argument and returning a boolean indicating if the `case` is selected.
+
 ## 2 - Cases collection
 
 ### `@parametrize_with_cases`

docs/index.md

@@ -292,20 +292,19 @@ def test_foo(a):
 @parametrize_with_cases("data", cases='.', 
                         filter=lambda cf: "success" in cf._pytestcase.id)
 def test_good_datasets2(data):
-    assert sqrt(data) > 0
+    ...
 ```
 
- - pytest-cases offers you an array of default filter for you to choose from in the `filters` module such as: `has_tag`, `has_prefix`, and etc. You can use logical operations on them like "and" (&) "or" (|) and "invert" (~) in order to create you own custom filters.
+ - An array of default filters is available in the `filters` module: `has_tag`, `id_has_prefix`, etc. You can use logical operations on them such as "and" (`&`) "or" (`|`) and "not" (`~`) in order to create your own custom filters. See [API reference](./api_reference.md#the-filters-submodule) for details.
 
 ```python
-from pytest_cases import filters
+from pytest_cases import filters as ft
 
 
 @parametrize_with_cases("data", cases='.',
-                        filter=filters.has_tag("success") & filters.id_has_prefix(
-                            "case_b")
+                        filter=ft.has_tag("success") & ft.id_has_prefix("case_b")
 def test_good_datasets3(data):
-    assert sqrt(data) > 0
+    ...
 ```