Raymond Hettinger email@example.com added the comment:
Consider breaking the operator module documents into sections, grouping all of the in-place ops into the last section. Start that section with a full description of how in-place works in python and show some examples of successful way to use the in-place operators.
Right now, the docs are somewhat misleading because they imply that the i-functions can be used in the same was as their counterparts.
---------- nosy: +rhettinger