document equivalent generator expressions for filters

closes #1068

diff --git a/jinja2/filters.py b/jinja2/filters.py
index 19f386413e3c41348f5dd8eeb2595bcdcdd672a5..57da0502c83a8b6c81b09bed68cc8a282cc4c8aa 100644 (file)
--- a/jinja2/filters.py
+++ b/jinja2/filters.py
@@ -1042,6 +1042,14 @@ def do_map(*args, **kwargs):
 
         Users on this page: {{ titles|map('lower')|join(', ') }}
 
+    Similar to a generator comprehension such as:
+
+    .. code-block:: python
+
+        (u.username for u in users)
+        (u.username or "Anonymous" for u in users)
+        (do_lower(x) for x in titles)
+
     .. versionchanged:: 2.11.0
         Added the ``default`` parameter.
 
@@ -1070,6 +1078,13 @@ def do_select(*args, **kwargs):
         {{ numbers|select("lessthan", 42) }}
         {{ strings|select("equalto", "mystring") }}
 
+    Similar to a generator comprehension such as:
+
+    .. code-block:: python
+
+        (n for n in numbers if test_odd(n))
+        (n for n in numbers if test_divisibleby(n, 3))
+
     .. versionadded:: 2.7
     """
     return select_or_reject(args, kwargs, lambda x: x, False)
@@ -1088,6 +1103,12 @@ def do_reject(*args, **kwargs):
 
         {{ numbers|reject("odd") }}
 
+    Similar to a generator comprehension such as:
+
+    .. code-block:: python
+
+        (n for n in numbers if not test_odd(n))
+
     .. versionadded:: 2.7
     """
     return select_or_reject(args, kwargs, lambda x: not x, False)
@@ -1109,6 +1130,13 @@ def do_selectattr(*args, **kwargs):
         {{ users|selectattr("is_active") }}
         {{ users|selectattr("email", "none") }}
 
+    Similar to a generator comprehension such as:
+
+    .. code-block:: python
+
+        (u for user in users if user.is_active)
+        (u for user in users if test_none(user.email))
+
     .. versionadded:: 2.7
     """
     return select_or_reject(args, kwargs, lambda x: x, True)
@@ -1128,6 +1156,13 @@ def do_rejectattr(*args, **kwargs):
         {{ users|rejectattr("is_active") }}
         {{ users|rejectattr("email", "none") }}
 
+    Similar to a generator comprehension such as:
+
+    .. code-block:: python
+
+        (u for user in users if not user.is_active)
+        (u for user in users if not test_none(user.email))
+
     .. versionadded:: 2.7
     """
     return select_or_reject(args, kwargs, lambda x: not x, True)