Terry J. Reedy <tjre...@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 <rep...@bugs.python.org>
<http://bugs.python.org/issue9717>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
