Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy).

1 files changed, 16 insertions, 8 deletions

diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst
index defb47c..44c09c3 100644
--- a/Doc/tutorial/datastructures.rst
+++ b/Doc/tutorial/datastructures.rst
@@ -19,13 +19,13 @@ objects:
 .. method:: list.append(x)
    :noindex:
 
-   Add an item to the end of the list; equivalent to ``a[len(a):] = [x]``.
+   Add an item to the end of the list.  Equivalent to ``a[len(a):] = [x]``.
 
 
 .. method:: list.extend(L)
    :noindex:
 
-   Extend the list by appending all the items in the given list; equivalent to
+   Extend the list by appending all the items in the given list.  Equivalent to
    ``a[len(a):] = L``.
 
 
@@ -40,8 +40,8 @@ objects:
 .. method:: list.remove(x)
    :noindex:
 
-   Remove the first item from the list whose value is *x*. It is an error if there
-   is no such item.
+   Remove the first item from the list whose value is *x*.  It is an error if
+   there is no such item.
 
 
 .. method:: list.pop([i])
@@ -70,13 +70,14 @@ objects:
 .. method:: list.sort()
    :noindex:
 
-   Sort the items of the list, in place.
+   Sort the items of the list in place.
 
 
 .. method:: list.reverse()
    :noindex:
 
-   Reverse the elements of the list, in place.
+   Reverse the elements of the list in place.
+
 
 An example that uses most of the list methods::
 
@@ -99,6 +100,10 @@ An example that uses most of the list methods::
    >>> a
    [-1, 1, 66.25, 333, 333, 1234.5]
 
+You might have noticed that methods like ``insert``, ``remove`` or ``sort`` that
+modify the list have no return value printed -- they return ``None``. [1]_  This
+is a design principle for all mutable data structures in Python.
+
 
 .. _tut-lists-as-stacks:
 
@@ -438,7 +443,7 @@ using a non-existent key.
 
 Performing ``list(d.keys())`` on a dictionary returns a list of all the keys
 used in the dictionary, in arbitrary order (if you want it sorted, just use
-``sorted(d.keys())`` instead). [1]_  To check whether a single key is in the
+``sorted(d.keys())`` instead). [2]_  To check whether a single key is in the
 dictionary, use the :keyword:`in` keyword.
 
 Here is a small example using a dictionary::
@@ -622,6 +627,9 @@ interpreter will raise a :exc:`TypeError` exception.
 
 .. rubric:: Footnotes
 
-.. [1] Calling ``d.keys()`` will return a :dfn:`dictionary view` object.  It
+.. [1] Other languages may return the mutated object, which allows method
+       chaining, such as ``d->insert("a")->remove("b")->sort();``.
+
+.. [2] Calling ``d.keys()`` will return a :dfn:`dictionary view` object.  It
        supports operations like membership test and iteration, but its contents
        are not independent of the original dictionary -- it is only a *view*.