document formatting methods in format filter

closes #566

diff --git a/jinja2/filters.py b/jinja2/filters.py
index 40dbfcb3a358201536c5188b66573e47bf5c52cf..19f386413e3c41348f5dd8eeb2595bcdcdd672a5 100644 (file)
--- a/jinja2/filters.py
+++ b/jinja2/filters.py
@@ -743,13 +743,24 @@ def do_float(value, default=0.0):
 
 
 def do_format(value, *args, **kwargs):
-    """
-    Apply python string formatting on an object:
+    """Apply the given values to a `printf-style`_ format string, like
+    ``string % values``.
 
     .. sourcecode:: jinja
 
-        {{ "%s - %s"|format("Hello?", "Foo!") }}
-            -> Hello? - Foo!
+        {{ "%s, %s!"|format(greeting, name) }}
+        Hello, World!
+
+    In most cases it should be more convenient and efficient to use the
+    ``%`` operator or :meth:`str.format`.
+
+    .. code-block:: text
+
+        {{ "%s, %s!" % (greeting, name) }}
+        {{ "{}, {}!".format(greeting, name) }}
+
+    .. _printf-style: https://docs.python.org/library/stdtypes.html
+        #printf-style-string-formatting
     """
     if args and kwargs:
         raise FilterArgumentError('can\'t handle positional and keyword '