[New-bugs-announce] [issue4986] Augmented Assignment / Operations Confusion in Documentation

[andrew cooke]

New submission from andrew cooke <andrew at acooke.org>:

There's a small confusion in terminology in the documentation related to
methods that implement augmented assignment.

The "Expressions" section of the language reference ("Simple
statements") refers to augmented assignment -
http://docs.python.org/3.0/reference/simple_stmts.html#augmented-assignment-statements
- and this seems to be a carefully chosen (and correct) phrase because
the parsing is related to assignments, which are augmented with various
operators.

It is important to note that augmented assignments ("+=" etc) are *not*
parsed as operators.  It is syntax error to use them in many places
where an operator would be accepted.

In the "Data Model" section, however, things are less clear
http://docs.python.org/3.0/reference/datamodel.html#emulating-numeric-types
.  The methods used to implement augmented assignment are grouped near
those used to implement arithmetic operators.  That seems natural.  But
the text confuses the two more than is strictly necessary.  In
particular there is the phrase "augmented arithmetic operations".

As I have already tried to make clear, these are not operations.  They
are augmented assignments.  Calling them operations is misleading,
because they cannot be used in the same places as "real" operations -
the parser simply will not accept them.

Apart from changing "augmented arithmetic operations" to "augmented
assignments" it might be worth adding some kind of note that explains to
the user that the parser calls those methods to implement assignment,
and that they are not valid in the same syntax as operations.

I am not sure the following will help, but it does illustrate the
confusion caused -
http://groups.google.com/group/comp.lang.python/browse_thread/thread/f1322928300b2b71

Cheers, Andrew

----------
assignee: georg.brandl
components: Documentation
messages: 80098
nosy: acooke, georg.brandl
severity: normal
status: open
title: Augmented Assignment / Operations Confusion in Documentation
versions: Python 3.0

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