[docs] [issue9717] operator module - "in place" operators documentation

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

I agree that the docs for augmented assignments and the corresponding method and funciton can and should be improved.

But I do not like this as is. In particular, Python does not have in-place operators; it has methods that optionally do an operation in-place if the first argument (self) is mutable. I think adding "" is insufficient to avoid the confusion of the incorrect term. What I think should be said is that the ixxx methods and the corresponding operator.ixxx functions implement the operation part of operation-augmented assignments.

For the operator doc, I think we should expand the initial paragraph ("The operator module ...") a bit so that less needs to said specifically for the ixxx functions.

Also, most of your explanation is really about augmented assignment and the .__ixxx__ special methods, not specifically about operator.ixxx functions, and might better be added to the subsection 3.3.6. Emulating numeric typesof the special methods section (and cross-referenced from the operator doc) or even used to improve 6.2.1. Augmented assignment statements, and not buried in the operator doc. If people are confused about the .ixxx functions, they are probably confused also about a.a. and .__ixxx__ methods.

So I would like to attack the whole problem and expand this issue to "Improve operator-augmented assginment docs." and cover all three relevant doc areas, starting with
6.2.1. Augmented assignment statements. As already hinted, I would like to expand the title to "Operator-augmented assignment statements.".

I would like there to be a prototype example near the top: either "target_arg op= arg", with op explained as one of +-*/... or "target_arg += arg" as a specific example, or both. Since the target is also an arg reference, it obviously must refer to a single existing object. Then discuss the two cases of target immutable and mutable, as the current doc and your proposal does.

Otherwise in this section, I am mystified by the reference of "(See section Primaries for the syntax definitions for the last three symbols.)". I have also forgotten the meaning of "With the exception of assigning to tuples "; i should just be stated.

As already stated, I also believe the explanation of .__ixxx__ methods in 3.3.6. Emulating numeric types could be improved a bit.

----------
nosy: +terry.reedy
stage:  -> patch review
versions: +Python 2.7, Python 3.1, Python 3.2 -Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue9717>
_______________________________________