diff -r 3784b6000640 Doc/library/stdtypes.rst
--- a/Doc/library/stdtypes.rst	Fri Oct 07 16:17:50 2011 +0200
+++ b/Doc/library/stdtypes.rst	Sat Oct 08 08:59:51 2011 -0700
@@ -15,6 +15,8 @@
 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 never return the collection instance itself but instead return an item from the instance or 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 -r 3784b6000640 Doc/tutorial/datastructures.rst
--- a/Doc/tutorial/datastructures.rst	Fri Oct 07 16:17:50 2011 +0200
+++ b/Doc/tutorial/datastructures.rst	Sat Oct 08 08:59:51 2011 -0700
@@ -7,6 +7,8 @@
 This chapter describes some things you've learned about already in more detail,
 and adds some new things as well.
 
+For lists, sets, and dicts, methods that change the contents or order never return the instance. Methods that mutate the object never return the instance.
+
 .. _tut-morelists:
 
 More on Lists
@@ -19,13 +21,13 @@
 .. 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 and return None. 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 and return None. Equivalent to
    ``a[len(a):] = L``.
 
 
@@ -40,7 +42,7 @@
 .. method:: list.remove(x)
    :noindex:
 
-   Remove the first item from the list whose value is *x*. It is an error if there
+   Remove the first item from the list whose value is *x* and return None. It is an error if there
    is no such item.
 
 
@@ -70,7 +72,7 @@
 .. method:: list.sort()
    :noindex:
 
-   Sort the items of the list, in place.
+   Sort the items of the list, in place and return None.
 
 
 .. method:: list.reverse()
diff -r 3784b6000640 Objects/listobject.c
--- a/Objects/listobject.c	Fri Oct 07 16:17:50 2011 +0200
+++ b/Objects/listobject.c	Sat Oct 08 08:59:51 2011 -0700
@@ -2329,16 +2329,16 @@
 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(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*);