[ python-Bugs-1454855 ] Explanation of pow() in lib

[SourceForge.net]

Bugs item #1454855, was opened at 2006-03-20 20:54
Message generated for change (Comment added) made by cito
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1454855&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Not a Bug
Status: Closed
Resolution: Works For Me
Priority: 2
Submitted By: Christoph Zwerschke (cito)
Assigned to: Nobody/Anonymous (nobody)
Summary: Explanation of pow() in lib

Initial Comment:
The Python Lib Reference explains the pow() function in
section 2.1 like that:

>>>
pow(  	x, y[, z])
    Return x to the power y; if z is present, return x
to the power y, modulo z (computed more efficiently
than pow(x, y) % z). The arguments must have numeric
types. With mixed operand types, the coercion rules for
binary arithmetic operators apply. For int and long int
operands, the result has the same type as the operands
(after coercion) unless the second argument is
negative; in that case, all arguments are converted to
float and a float result is delivered. For example,
10**2 returns 100, but 10**-2 returns 0.01.
<<<

The problem is here that the notation 10**2 is used in
the example without prior explanation that it is
equivalent to pow(10,2). A newbie reading the docs in
linear order may not know this here (many other
languages write x^y instead of x**y). The notation x**y
is only introduced later in section 2.3.4.

I recommend adding a short remark to this paragraph
explaining that instead of writing pow(x,y) you can
also write x**y.

----------------------------------------------------------------------

>Comment By: Christoph Zwerschke (cito)
Date: 2006-03-20 23:23

Message:
Logged In: YES 
user_id=193957

I'm not sure about that. You are thinking too much from an
expert/insider point of view, not from a newbie/learner
point of view.

For newbies, this is not so clear. See for example:
http://groups.google.com/group/comp.lang.python/browse_frm/thread/c82eb3c3a6068b7d

Even if the reader understands what 10**2 is, it is still
not clear at this place whether this is a Python expression
or simply a mathematical notation, and whether pow(x,y)
behaves exactly like x**y or not.

I still think a short note like "Note that you can also
write x**y as an abbreviation for pow(x,y)." makes all of
this clear and may be a help or a hint for newbies and
non-mathematicians.

Your argument that the Lib reference is not meant to be read
like a novel is true, but the introduction says explicitely
that reading it as a novel *is* an option, and encourages
people to read at least chapter 2 which is actually one of
the core parts of the whole Python documentation. So I think
many newbies will read the Tutorial (where the equivalence
of x**y and pow(x,y) is not mentioned either) and then at
least chapter 2 from the Lib reference. And even if you take
it only as a reference and just read the explanation of
pow() it may be a good reminder that pow(x,y) is actually
the same as x**y.

----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2006-03-20 21:07

Message:
Logged In: YES 
user_id=80475

The Lib Reference is like an encylopaedia; it does not 
purport to avoid forward references and be read linearly 
start to finish.

Also, in this case the meaning is 100% clear from the 
context.  IOW, given a discussion about x raised to the y 
power and an expression "10**2 returns 100, but 10**-2 
returns 0.01", the meaning of the operator is self-evident.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1454855&group_id=5470