[docs] [issue12192] Doc that collection mutation methods return item or None
report at bugs.python.org
Fri May 27 10:52:53 CEST 2011
Ezio Melotti <ezio.melotti at gmail.com> added the comment:
I find this wording a little confusing: "For lists, sets, and dicts, methods that change the contents or order never return the instance. Instead, they return an item from the instance or, more commonly, None.".
I would suggest to drop the second part because we don't care about those methods now and because some of them return None too, and simply use "Methods that mutate the object never return the instance.", possibly adding something like "to remind you that no new objects have been created.".
The same wording can be used in both the Tutorial and the Library Manual (if readers happen to read it twice, it's even more likely that they will remember it).
FWIW the glossary has entries for "mutable" and "immutable", adding a note about this convention in the "mutable" entry might be a good idea too.
Adding the '-> None' in the docstring is fine too, I'm not sure about the footnote.
Terry, do you want to work on a patch?
stage: -> needs patch
Python tracker <report at bugs.python.org>
More information about the docs