bpo-16011: clarify that 'in' always returns a boolean value (GH-152) (GH-883)
(cherry picked from commit 0ae7c8bd614d3aa1fcaf2d71a10ff1148c80d9b5)
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 989fb61..df6e849 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -1249,37 +1249,30 @@
Membership test operations
--------------------------
-The operators :keyword:`in` and :keyword:`not in` test for collection
-membership. ``x in s`` evaluates to true if *x* is a member of the collection
-*s*, and false otherwise. ``x not in s`` returns the negation of ``x in s``.
-The collection membership test has traditionally been bound to sequences; an
-object is a member of a collection if the collection is a sequence and contains
-an element equal to that object. However, it make sense for many other object
-types to support membership tests without being a sequence. In particular,
-dictionaries (for keys) and sets support membership testing.
+The operators :keyword:`in` and :keyword:`not in` test for membership. ``x in
+s`` evaluates to ``True`` if *x* is a member of *s*, and ``False`` otherwise.
+``x not in s`` returns the negation of ``x in s``. All built-in sequences and
+set types support this as well as dictionary, for which :keyword:`in` tests
+whether the dictionary has a given key. For container types such as list, tuple,
+set, frozenset, dict, or collections.deque, the expression ``x in y`` is equivalent
+to ``any(x is e or x == e for e in y)``.
-For the list and tuple types, ``x in y`` is true if and only if there exists an
-index *i* such that either ``x is y[i]`` or ``x == y[i]`` is true.
-
-For the Unicode and string types, ``x in y`` is true if and only if *x* is a
-substring of *y*. An equivalent test is ``y.find(x) != -1``. Note, *x* and *y*
-need not be the same type; consequently, ``u'ab' in 'abc'`` will return
-``True``. Empty strings are always considered to be a substring of any other
-string, so ``"" in "abc"`` will return ``True``.
-
-.. versionchanged:: 2.3
- Previously, *x* was required to be a string of length ``1``.
+For the string and bytes types, ``x in y`` is ``True`` if and only if *x* is a
+substring of *y*. An equivalent test is ``y.find(x) != -1``. Empty strings are
+always considered to be a substring of any other string, so ``"" in "abc"`` will
+return ``True``.
For user-defined classes which define the :meth:`__contains__` method, ``x in
-y`` is true if and only if ``y.__contains__(x)`` is true.
+y`` returns ``True`` if ``y.__contains__(x)`` returns a true value, and
+``False`` otherwise.
For user-defined classes which do not define :meth:`__contains__` but do define
-:meth:`__iter__`, ``x in y`` is true if some value ``z`` with ``x == z`` is
+:meth:`__iter__`, ``x in y`` is ``True`` if some value ``z`` with ``x == z`` is
produced while iterating over ``y``. If an exception is raised during the
iteration, it is as if :keyword:`in` raised that exception.
Lastly, the old-style iteration protocol is tried: if a class defines
-:meth:`__getitem__`, ``x in y`` is true if and only if there is a non-negative
+:meth:`__getitem__`, ``x in y`` is ``True`` if and only if there is a non-negative
integer index *i* such that ``x == y[i]``, and all lower integer indices do not
raise :exc:`IndexError` exception. (If any other exception is raised, it is as
if :keyword:`in` raised that exception).