diff --git a/doc/reference/qweb.rst b/doc/reference/qweb.rst
index 2954d0bf167..a4a5b3769a4 100644
--- a/doc/reference/qweb.rst
+++ b/doc/reference/qweb.rst
@@ -136,16 +136,16 @@ attribute, and
 is equivalent to the previous example.
 
 ``foreach`` can iterate on an array (the current item will be the current
-value), a mapping (the current item will be the current key) or an integer
-(equivalent to iterating on an array between 0 inclusive and the provided
-integer exclusive).
+value) or a mapping (the current item will be the current key). Iterating on an
+integer (equivalent to iterating on an array between 0 inclusive and the
+provided integer exclusive) is still supported but deprecated.
 
 In addition to the name passed via ``t-as``, ``foreach`` provides a few other
 variables for various data points:
 
 .. warning:: ``$as`` will be replaced by the name passed to ``t-as``
 
-:samp:`{$as}_all`
+:samp:`{$as}_all` (deprecated)
     the object being iterated over
 
     .. note:: This variable is only available on JavaScript QWeb, not Python.
@@ -164,16 +164,15 @@ variables for various data points:
     whether the current item is the last of the iteration (equivalent to
     :samp:`{$as}_index + 1 == {$as}_size`), requires the iteratee's size be
     available
-:samp:`{$as}_parity`
+:samp:`{$as}_parity` (deprecated)
     either ``"even"`` or ``"odd"``, the parity of the current iteration round
-:samp:`{$as}_even`
+:samp:`{$as}_even` (deprecated)
     a boolean flag indicating that the current iteration round is on an even
     index
-:samp:`{$as}_odd`
+:samp:`{$as}_odd` (deprecated)
     a boolean flag indicating that the current iteration round is on an odd
     index
 
-
 These extra variables provided and all new variables created into the
 ``foreach`` are only available in the scope of the``foreach``. If the
 variable exists outside the context of the ``foreach``, the value is copied
@@ -217,7 +216,9 @@ exists in 3 different forms:
     string (e.g. classes)::
 
         <t t-foreach="[1, 2, 3]" t-as="item">
-            <li t-attf-class="row {{ item_parity }}"><t t-esc="item"/></li>
+            <li t-attf-class="row {{ (item_index % 2 === 0) ? 'even' : 'odd' }}">
+                <t t-esc="item"/>
+            </li>
         </t>
 
     will be rendered as::