[ 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 (Tracker Item Submitted) made by Item Submitter
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: Open
Resolution: None
Priority: 5
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.

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

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