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

3 files changed, 24 insertions, 12 deletions

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 46f0f9f..559921a 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -15,6 +15,10 @@ interpreter.
 The principal built-in types are numerics, sequences, mappings, classes,
 instances and exceptions.
 
+Some collection classes are mutable.  The methods that add, subtract, or
+rearrange their members in place, and don't return a specific item, never return
+the collection instance itself but ``None``.
+
 Some operations are supported by several object types; in particular,
 practically all objects can be compared, tested for truth value, and converted
 to a string (with the :func:`repr` function or the slightly different
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*.
diff --git a/Objects/listobject.c b/Objects/listobject.c
index 28d94e7..049f2a8 100644
--- a/Objects/listobject.c
+++ b/Objects/listobject.c
@@ -2329,16 +2329,16 @@ PyDoc_STRVAR(clear_doc,
 PyDoc_STRVAR(copy_doc,
 "L.copy() -> list -- a shallow copy of L");
 PyDoc_STRVAR(append_doc,
-"L.append(object) -- append object to end");
+"L.append(object) -> None -- append object to end");
 PyDoc_STRVAR(extend_doc,
-"L.extend(iterable) -- extend list by appending elements from the iterable");
+"L.extend(iterable) -> None -- extend list by appending elements from the iterable");
 PyDoc_STRVAR(insert_doc,
 "L.insert(index, object) -- insert object before index");
 PyDoc_STRVAR(pop_doc,
 "L.pop([index]) -> item -- remove and return item at index (default last).\n"
 "Raises IndexError if list is empty or index is out of range.");
 PyDoc_STRVAR(remove_doc,
-"L.remove(value) -- remove first occurrence of value.\n"
+"L.remove(value) -> None -- remove first occurrence of value.\n"
 "Raises ValueError if the value is not present.");
 PyDoc_STRVAR(index_doc,
 "L.index(value, [start, [stop]]) -> integer -- return first index of value.\n"
@@ -2348,7 +2348,7 @@ PyDoc_STRVAR(count_doc,
 PyDoc_STRVAR(reverse_doc,
 "L.reverse() -- reverse *IN PLACE*");
 PyDoc_STRVAR(sort_doc,
-"L.sort(key=None, reverse=False) -- stable sort *IN PLACE*");
+"L.sort(key=None, reverse=False) -> None -- stable sort *IN PLACE*");
 
 static PyObject *list_subscript(PyListObject*, PyObject*);