[docs] [issue16701] Docs missing the behavior of += (in-place add) for lists.
report at bugs.python.org
Fri Sep 18 19:32:39 CEST 2015
Brendan Barnwell added the comment:
This needs to be fixed. The documentation for the behavior of += on lists needs to be with the documentation on lists. The existing, vague documentation that += works in-place "when possible" is insufficient.
A central feature of Python is that the behavior of operators like + and += is overridable on a per-type basis. Hence, the Language Reference is not the appropriate place for describing the behavior of += on a particular type. The behavior of += on lists should be documented where the behavior of lists is documented (as, for instance, the behavior of + on lists already is), not where the syntax of += is documented.
Someone just asked a question on StackOverflow about this (http://stackoverflow.com/questions/32657637/python-changing-variables-vs-arrays-in-functions/32657770#32657770). It is embarrassing to have to tell people, "To know what += does on a type, you need to look at the documentation for that type. . . except that the documentation for the builtin types doesn't document what some operators do."
Python tracker <report at bugs.python.org>
More information about the docs